Statamic V1.6 has been out for almost a week. So I pour myself a bit of Don Julio 1942 (fine tequila or scotch are the only things that will do in this situation) with 2 ice cubes in a glass, block off a bit of time and sit down to take a look at the new Control Panel theme and Raven.

Pedantic introductions aside… this control panel is gorgeous. Such a pleasure to use. They've moved some things around but I like it. It seemed a bit odd, in the previous version, to land on the system information after logging in. Users don't necessarily need to see that info. They, more than likely, came there to manage content not to check system file security. So it is a nice change to land on content first. The control panel is responsive in speed and viewport adjustment. Mobile usage is nicely done. I'm also really digging the ability to filter based on a section or type of content. I think usability with non-technical users will be really nice when combined with the custom field capability that is similar to ExpressionEngine's Channel Publish page.

Raven is really really cool. To quote the Statamic Overview page for Raven.

Forms never saw this bad ass coming.

It is pretty cool and after only a little bit of playing with it I know I am only scratching the surface. In an effort to come to grips with Raven I will first try converting the contact form we have been working on in previous blog posts to a Raven fueled form.

To begin you have to download Raven. You'll need to upload a few files. In _config/add-ons you'll upload the Raven folder from the package you downloaded. We'll return to this folder in a minute as it contains some powerful things. Next you'll upload the Raven folder to _add-ons. Installation? Complete. I love this system.

So go back to the _config/add-ons/raven folder. See that folder called form sets? Open the example.yaml file in your favorite text editor. This is basically where you set all of the cool parameters for Raven. I'll spare you the details of each and every parameter and just highlight the settings I used in mine.

submission_save_path: _content/_forms/

This is where it will save the submissions on your server. You'll see in a minute how you configure it to send you an email as well. But I bring this location up because, as you can see, it is inside of the _content folder. This means you can output this stuff on the front end of the site if you like.

file_prefix: contact

I went ahead and set a prefix for my files in case I have another form. This way I can tell the entries they create apart.

required:
  - name
validate:
  name: alpha

Just want to see what happens when this fails (in the next blog post)

email:
  to: marcus@bluefishdesignstudio.com
  from: "{{ from }}"
  subject: The raven has flown
  automagic: true

This is the one that I am jazzed about. See that from field? The {{ from }} in there will contain the email address of the person submitting the form. I've not asked but I am betting that you can use that same format in the other fields as well. So if you wanted to dynamically set the subject you could.

Save the file.

Go to _themes/denali/templates and open contact.yaml. We need to change a few things if we are going to use Raven. Actually the code we will be adding should make things a lot cleaner.

You can delete all of this:

    {{ if error}}
        

Error

  • {{ errors }}
  • {{error}}
  • {{ /errors }}

{{ endif }} {{ if success }}

{{ thankyou }}

{{ else }}

And instead of this:

{{ email_form subject="Contact Form" to="marcus@bluefishdesignstudio.com" required="first-name" }}

All you need is this:

{{ raven:form formset="contact" return="contact-us" }}

The formset parameter tells Raven to look at that file we made changes to at the beginning of this tutorial. And as you might suspect the return parameter tells it to return back to the same page. Make sure to replace the ending {{ /email_form }} with {{ /raven:form }} and delete the unnecessary conditional logic between the raven:form tag pair. No worries if this is a bit confusing. Just look to the end of this blog post and I will provide full code for the files we've talked about.

Now, above the raven:form tag pair put this:

{{ if raven:success }}
	
{{ thankyou }}

{{ endif }}

The raven:success and raven:has_errors are new tag pairs that Jack added to make things simpler. I'll only show you the raven:success in this blog post and talk a bit about raven:has_errors in the next.

Notice that in the code above we are still using our {{ thank you }} to output a custom message when the person completes the form successfully.

Provided you have edited your code properly your _themes/denali/templates/contact.html file should look like so:


 

{{ title }}

{{ if email }}

Email Address:Email Address

{{ endif }} {{ if phone }}

Phone Number: {{ phone }}

{{ endif }} {{ if twitter|dribbble|facebook|linkedin }}
  • {{ endif }} {{ if twitter }}
  • Twitter
  • {{ endif }} {{ if dribbble }}
  • Dribbble
  • {{ endif }} {{ if facebook }}
  • Facebook
  • {{ endif }} {{ if linkedin }}
  • Linkedin
  • {{ endif }} {{ if twitter|dribbble|facebook|linkedin }}
{{ endif }} {{ instructions }}
{{ if raven:success }}
{{ thankyou }}
{{ endif }} {{ raven:form formset="contact" return="contact-us" }}Your Name:
First Name*
Last Name*
Email Address*
Phone Number*
Company
What is your timeline?* -- Select One --ImmediatelyWithin 2 MonthsWithin 4 MonthsHadn't really thought about it
What is your budget?* -- Select One --$5k to $10k$10k to $15k$15k to $20k$20k to $30kHadn't really thought about it
Your Message*
 
{{ /raven:form }}

and your _config/add-ons/raven/formset/contact.yaml file will look like so:

###########################################################################################
#
#  EXAMPLE RAVEN FORMSET
#
#  Formsets can override any default settings (raven.yaml) EXCEPT master_killswitch
#
###########################################################################################

# Location (from root) to save form submissions
submission_save_path: _content/_forms/

# Prefix your files with a string which are saved in the format:
# YYYY-MM-DD-HH-MM-SS.yaml
file_prefix: contact

# Fields allowed to be submitted in the form, automatically
# purging anything and everything else
#allowed:
#  - first-name
#  - last-name
#  - from
#  - phone

# You are not required to require fields, but once you do, any missing
# from the POST will squash this submission and send a list of
# missing fields to your {{ raven:errors }} tagpair
required:
  - name

# Apply validation rules to specific fields. Refer to documentation
# for a full list of available rules and their format
validate:
  name: alpha

# Error messages can be mapped to your fields and passed to the
# template upon failure. They will be available here:
#
# {{ raven:error }}
#     {{ invalid }}
#         {{ field }} : {{ message }}
#     {{ /invalid }}
# {{ /raven:error }}
#
# messages:
#   name: "Must be made of letters. Who named you?"
#   website: "That's not a website. Are you from the past?"
#   birthday: "You need to be 21 to drink. Come back later."
#   favorite_number: "Ahem. I said 3 digit number."

# Configure notification email
email:
  to: marcus@bluefishdesignstudio.com
  from: "{{ from }}"
  subject: The raven has flown
  automagic: true
#  html_template: html_email
#  text_template: text_email

Now if you go to the front end of the website and navigate to the form we've been working on you'll see it looks like just before. If you enter in info and submit it you should see what ever message you had in thankyou field in your Contact Us entry.

Next I may try and take a look at submitting content through a Raven form. No promises though. I will at least take a quick look at the error messaging capabilities of Raven.

Now raise your glass to Jack and Fred (makers of Statamic) and take another swig of that tequila (or scotch).

EDIT: Jack has moved the formsets folder for the V1 release. So just make note of it's new location in _config/formsets. That is all :)