Options for Statamic Add-ons' Configuration

tl;dr

$this->fetch() > $this->fetchParam() + $this->fetchConfig()

Also, $this->config() is pretty awesome.


When creating add-ons with Statamic, you have a few choices for setting configuration. You can use

  1. parameters,
  2. a settings file, or best of all
  3. allow the site crafter to decide!

How to Use Parameters

As stated in the Statamic docs, you can grab parameters from a tag with $this->fetchParam('your_param_here').

My plugin, Hash Browns (shameless plug!), demonstrates this well. The following excerpt grabs the page_wrap parameter and assigns it to a JavaScript variable for use later on in the code. This empowers site crafters to choose their own class/id name, rather than forcing them to use my preference.

$this->return_data .= "
  var $page_wrap = $('" . $this->fetchParam('page_wrap') . "');
";

Following this method, the site crafter would use code similar to this:

{{ hash_browns page_wrap="#wrapper" }}

How to Use a Settings File

Also stated on the same page of the Statamic docs, you can grab parameters from a settings file with $this->fetchConfig('your_yaml_var_here').

Let’s edit the previous example code to use a settings file instead. That way site crafters don’t have to type that same code over and over again on each layout / template / partial that requires a {{ hash_browns }} tag (most people usually only use a Hash Browns tag on a single layout, but for example’s sake…).

$this->return_data .= "
  var $page_wrap = $('" . $this->fetchConfig('page_wrap') . "');
";

Now instead of using {{ hash_browns page_wrap="wrapper" }} on each page, this setting can be configured in config/add-ons/hash_browns/hash_browns.yaml like so:

page_wrap: '#wrapper'

Now site crafters can just type the following to achieve the same result.

{{ hash_browns }}

How to Be More Flexible

Also also stated on the same page of the Statamic docs, you can let the site crafter use their own preference with $this->fetch('your_param_or_yaml_var_here'). Using this method, site crafters can even set a default in the settings file and override as needed with a parameter.

So now let’s say the plugin says:

$this->return_data .= "
  var $page_wrap = $('" . $this->fetch('page_wrap') . "');
";

The config file says:

page_wrap: '#wrapper'

Finally, the tag says:

{{ hash_browns page_wrap="#wrap" }}

Hash Browns reads the value as #wrap.

Bonus Options!

We have other undocumented (I think…) choices.

Don’t go using these without good reason. The fetch methods exist for a reason. You should always use the API whenever possible.

Config File

One powerful method grabs all configuration settings from the file. It then creates an array with each yaml variable as a key. Jack mentioned this method on twitter:

StayPal uses this method so that I don’t need to hard code each of PayPal’s HTML variables. StayPal users can just throw in whichever ones they want/need and this method handles the rest.

Here it is:

$this->config

Now, access your values with $this->config['your_param_or_yaml_var_here'].

Parameters

The other method works much like $this->config, but instead grabs all the parameters.

$this->attributes

comments powered by Disqus