Pimp your blueprints

A quick tutorial to talk about a little-known Kirby blueprint feature that'll save you a lot of time and make your blueprints look way better!

Global blueprint fields

Yes, this tutorial is about global blueprint fields! If you've never heard of them, your life is about to change... Or at least, your blueprints will look way better!!

Global Fields in the docs

 

The basics of a field

Let's take it from the beginning. In Kirby, this is the structure of a field:

  • The first line is the name of the field.
  • The following lines are information and options for that field. Notice the indentation? It's YAML indentation which means if you don't use the proper indentation, your fields will break.

This is a field we use in all our blueprints. It's always the same. Isn't it annoying that we have to copy and paste it everywhere?

Just a basic seo description field

seodescription:
  type: text
  label: Page SEO description
  icon: search
  help: Use this to customize the description of your page in search engines and on social networks. Maximum 160 characters.
  validate:
    max: 160

Enter the Global Field Definitions

What's that?
I'll try to keep it simple: it's everything under the name of your field, neatly organized in its own file, that can be called from every blueprint.
You'll need to create a fields folder inside your site/blueprints folder. All your global field definitions will be stored there.
Let's do this for our seodescription field. The name of the file is important, as it's what you'll use to call the global field from your blueprints. Let's call it seodescription.yml.

Now copy everything under the name of your field and paste it in this new file. You should remove any indentation that's not necessary. We kept the indentation on the max: 160 line only.

site/blueprints/fields/seodescription.yml

type: text
label: Page SEO description
icon: search
help: Use this to customize the description of your page in search engines and on social networks. Maximum 160 characters.
validate:
  max: 160

Use it in your blueprint

Now that you've defined your field globally, you can call it from any blueprints. This is very simple:
yourfieldname: seodescription
That's it! This will give all the options defined in the seodescription.yml file to your field.

What's very neat about this is that you only need to change your field once for all your pages. For instance if you've decided to change your blueprints to use a new type of textarea field, say the Visual Markdown field for instance. You can now change this by editing one line in one single file instead of going over each individual blueprint.

You can even expand the field to change or add some options on a case by case basis, read how in the docs!

Stay tuned!

Want to always know the latest Maco news? Subscribe and receive the newsletter straight in your inbox. No spam guarantee!

Write a comment