Custom Fields

by Justin Stayton | Last edited: 1/22/2020

Content management systems like MonkCMS have to balance a fine line between offering enough fields for the majority of sites without becoming everything to everybody (which never ends well). We like to think MonkCMS has done this well, but there are inevitably sites that need fields outside of the scope MonkCMS has defined. Custom Fields solves this problem by allowing sites to add their own fields for capturing values to be displayed on their site.

How it Works

Creating Custom Fields

Custom Fields can be created through the backend module of the same name, found within the Admin tab. As an example, let's say a site needs to track the Twitter username of a Branch. There are four fields when adding a Custom Field:

  1. Module — All of the modules that currently support Custom Fields. Full list below. For our example, select Branches.
  2. Type — The different types of input fields. More on this later, but for now select Single Line Text.
  3. Label — The text to display next to the input field in the backend to describe what it's for. Since we're tracking Twitter username, "Twitter username" seems to be appropriate.
  4. API Tag — The API tag to output the value in the getContent call. This field is populated based on the Label value entered above (__customtwitterusername__). Feel free to shorten or change as you see fit.
Adding Custom Field Values in the Backend

Now that the Custom Field has been added, head over to the Branches module. On the add / edit screen for a Branch, there should now be a "Twitter username" field. Enter a value, hit Save, and you're done! Now the Twitter username of each Branch is stored alongside the rest of the information.

Dispaying Custom Field Values on the Client Site

Remember the API tag we created for displaying a Branch's Twitter username? (If not, it was __customtwitterusername__.) Go ahead and add this to either a Branch list or detail getContent call. The value entered in the backend should be output for the associated record.

Supported Modules

  • Articles
  • Blog Posts
  • Blogs
  • Booklists
  • Books
  • Branches
  • Churches
  • Discussions (Custom Fields are associated with the board, not categories or individual discussions)
  • Events (Custom Fields are associated with the master event and values cannot be changed per-occurrence)
  • Families
  • Galleries
  • Groups (Only through the Groups API, not any other APIs that output group details)
  • Link Lists (WYSIWYG Editor, Image, Video, Document, and Audio types not supported)
  • Pages
  • Playlists
  • Products
  • Rotator Slides (WYSIWYG Editor type not supported)
  • Rotators
  • Sections
  • Sermons
  • Songs
  • Users (Only through the Members API and MePage API, not any other APIs that output member details)

Field Types

There are eight Custom Field types:

  • Single Line Text — For a short amount of text, roughly one line in length. The text is returned through the API exactly as entered in the backend. Example fields: Twitter or Facebook username, reviewer rating (scale of 1-10), URL.
  • Paragraph Text — For longer, unformatted text. The text is returned through the API exactly as entered in the backend. Paragraph breaks are returned as newline (n) characters. Example fields: unformatted summary, short quoatation, raw HTML.
  • WYSIWYG Editor — For HTML formatted text and media. Example fields: formatted Book review, Gallery description, latest Branch news.
  • Checkbox — For use as conditionals in the API, much like the __ifnewwindow__ Link List API tag. When checked, a space (" ") is returned through the API; unchecked, nothing is returned, and the show line containing the tag is not output. For example, say you have a list of Branches displayed on your website. Most are in the United States, and for those you don't want to display the country name in the address. But for branches outside of the United States, you do want to display the country name. You could create a Custom Field checkbox with the label, "Display country name?" and then add the custom tag to the show line with the country tag: show:__customdisplaycountry__Country: __country__. This line is then only output for the Branch when the checkbox is checked in the backend. Check it for all international branches, and their country will be displayed on the site.
  • Image — Associate an existing image or upload a new one. The full URL to the image is returned through the API. All image caching/thumbnail parameters are available. Example fields: Church building photo, Group photo, back cover of Book.
    Custom Field Image
  • Video — Associate an existing video or upload a new one. The full URL to the video is returned through the API. The exception is embedded videos, which return the embeddable <iframe> HTML with support for height and width parameters (default is 560x315). Example fields: Blog Post video, low-quality Sermon video, Church tour video.
    Custom Field Video
  • Document — Associate an existing document or upload a new one. The full URL to the document is returned through the API. Example fields: Branch policies, User resume, Group rules.
    Custom Field Document
  • Audio — Associate an existing audio file or upload a new one. The full URL to the audio file is returned through the API. Example fields: Audiobook, Sermon announcements, podcast.
    Custom Field Audio

Constraints

  • Primarily for displaying custom values through the API. There is no way to group by a Custom Field, hide or show certain values, or any other more advanced API functions. That said, custom values are searchable in the backend (using Spotlight Search) and through the Search API.
  • Only seven (7) Custom Fields per module. This self-imposed limitation is to prevent too many Custom Fields from slowing down API requests.
  • Not all types supported by all modules. Not all of our add / edit form screens were designed with WYSIWYG editors or file upload fields in mind (such as Link Lists). The list of supported modules above details the exceptions.