whateverthing.com

☰

Recently I've started writing short stories and I've been thinking it would be fun to post them online somewhere. As it turns out, I've got the perfect place: right here! I've added a new area on the site to showcase the stories I've written. Tales from the Whateverthing can be found at the Short Stories link in the sidebar.

This also gives me a chance to demonstrate Sculpin 3's helpful new command for creating custom content types. This post will share some details about the initial command line parameters, as well as what went into customizing the skeleton files that were created.

First, we'll run /vendor/bin/sculpin help content:create to show the help screen for the new command.

You'll need to be running at least Sculpin 3.0 RC1 to have access to the command, but here is what its help screen looks like:

Description:
  Create a new content type.

Usage:
  content:create [options] [--] <type>

Arguments:
  type                           Name for this type (e.g., "posts")

Options:
  -b, --boilerplate              Generate boilerplate/placeholder/template files.
  -t, --taxonomy=TAXONOMY        Organize content by taxonomy categories ("tags",
                                 "categories", "types", etc) (multiple values allowed)
  -h, --help                     Display this help message
  -q, --quiet                    Do not output any message
  -V, --version                  Display this application version
      --ansi                     Force ANSI output
      --no-ansi                  Disable ANSI output
  -n, --no-interaction           Do not ask any interactive question
      --project-dir=PROJECT-DIR  The project directory. [default: "."]
  -e, --env=ENV                  The Environment name. [default: "dev"]
      --no-debug                 Switches off debug mode.
      --safe                     Enable safe mode (no bundles loaded, no kernel booted)
      --git-version              See Git version
  -v|vv|vvv, --verbose           Increase the verbosity of messages: 1 for normal
                                 output, 2 for more verbose output and 3 for debug

Help:
  The content:create command helps you create a custom content type and,
  optionally, the associated boilerplate/templates.

Many of these entries (like --no-ansi, --project-dir, or -vvv) can be ignored for now. We're interested in the parameters that are unique to content creation. Things like type and --boilerplate and --taxonomy.

Understanding the Parameters

Argument: <type>

I debated a bit on what I wanted to name my content type for short stories. A URL like /short-stories/ would be fine, but I felt that constantly referencing it in the YAML and markdown of my files might get a bit cumbersome.

Types are referred to in the plural form, like "posts" for a blog or "talks", "clients", "how-tos", and so on. Internally, the content create command singularizes the plural in order to create certain files and tie things together. The singularization code uses Doctrine's Inflector class, which supports hundreds of pluralization and singularization conversions.

Long story short, I ended up choosing "tales". I knew that it would be simple enough to singularize ("tale") and would make a nice URL (/tales/). Also, it sounds kind of fun.

Option: --boilerplate

The boilerplate flag controls whether skeleton files are created during the content creation process. Even though these files are extremely bare-bones, they are a useful starting point and help reduce confusion on how to implement things like pagination.

Highly recommended. In fact, I probably should have made it the default.

Option: --taxonomy

In Sculpin, taxonomies are a way of categorizing content. For example, blog posts generally come with two taxonomies: "tags" and "categories".

Those two examples aren't very well suited to fiction content, though, so I decided to organize my tales by Character and Collection.

Creating the Content Type

Here's what the final command looked like:

$ vendor/bin/sculpin content:create tales -b -t collections -t characters

That shows how it all ties together. The tales type, the boilerplate option, and the two taxonomies (collections and characters).

The command provides a bunch of output:

Generating new content type: tales
=============================================
YAML to add to app/config/sculpin_kernel.yml:
=============================================

sculpin_content_types:
    tales:
        type: path
        path: _tales
        singular_name: tale
        layout: tale
        enabled: true
        permalink: tales/:title
        taxonomies:
            - collections
            - characters

=================END OF YAML=================


Generating boilerplate for tales

This output provides sample YAML that needs to be added to your sculpin_site.yaml file in order for Sculpin to know about the content type's existence.

The boilerplate text at the bottom doesn't list the files that were created, but here they are to give an idea of what now exists:

source/_views/tale.html
source/_tales/
source/tales.html
source/tales/characters.html
source/tales/characters/character.html
source/tales/collections.html
source/tales/collections/collection.html

The Skeleton Key

Each of the files serves a unique purpose.

source/_views/tale.html

This file controls how individual Tales will be rendered. It displays the title and subtitle of the tale, and then the body content. At the bottom, it shows the Characters and Collections of the tale (if any are declared in the YAML front matter for that tale), as well as the date of publication.

source/_tales/

This folder is where each tale will live. It's empty to begin with, but an example tale would look something like this:

source/_tales/the-plums.md

---
layout: tale
title: The Plums
subtitle: I must have them
date: 2019-02-09
characters:
- Plums
collections:
- Delicious Things And How To Find Them
---
The plums.

The delicious plums.

I must have them...

...for I hunger.

For the plums.

source/tales.html

This is the main entry point into the Tales feature. By default, it lists the ten most recent entries. Older entries get shuffled into the pagination system.

source/tales/characters.html source/tales/collections.html

These two files are the gateway into browsing tales by taxonomy. They do not use pagination; if I end up with dozens of characters or collections, they'll all show up here and allow readers to click into the paginated listing of matching Tales.

source/tales/characters/character.html source/tales/collections/collection.html

These two files are similar to the source/tales.html file, in that they enable pagination of content. They list Tales by the selected Character or Collection, also defaulting to showing 10 per page.

Making It Pretty(ish)

I found that the new layouts were a little to skeletal for my liking. The first thing I did was make a copy of my "default" view layout. I called this new one source/_views/plain.html, and started chipping away at the blog-specific pieces that would interfere with reading Tales.

Then, I modified the source/_views/tale.html file to point at this new layout by changing the Twig extends directive to read {% extends 'plain' %} instead of {% extends 'default' %}.

After that, I decided to spruce up the taxonomy templates by updating their front matter to have a layout: default entry:

---
layout: default
use: [tales_characters]
---

I did this for all four of the taxonomy files (leaving the use line and other front matter lines unchanged).

This got things looking relatively nice and gave me a starting point for doing some CSS styling that I won't get into here.

Where To Go Next

This run-through of the content:create command has given me some ideas on how to improve it in future versions of Sculpin. As for Tales from the Whateverthing, I'm hopeful that I can expand on it and turn it into an entertaining part of the site.

Thanks for reading! Please sign up for the newsletter to be automatically notified of new stuff happening here.

---