How to Add Theme Settings for Drupal 7

by , Front-End Web Developer

You know that list of checkboxes on the theme settings page that let you turn on and off parts of the theme like the logo or slogan? Well, you can add your own options to that list really easily in Drupal 7. In D6, this was kind of a pain, because you had to write all sorts of functions to save and load your settings to the database and handle everything properly. In D7, that's all done through the Form API, so the heavy lifting is done for you. All you need to do is tell it to add some form fields, and what the new setting is called!

You'll need to create a theme-settings.php file in your theme, and add this code to it:

<?php
function themename_form_system_theme_settings_alter(&$form, &$form_state) {
  $form['theme_settings']['your_option'] = array(
    '#type' => 'checkbox',
    '#title' => t('Your Option'),
    '#default_value' => theme_get_setting('your_option'),
  );
}
  • ['theme_settings'] is the existing fieldset to add your option to. You can leave it off, but by pointing it to the theme_settings group, it'll be added to the existing list of checkbox display options for your theme. Handy!
  • ['your_option'] is the name of your new option.
  • #type tells Drupal what kind of form element to create.
  • #title is the title (or in this case, label) text for the form element.
  • #default_value tells Drupal where to find the initial setting for the form element.

We set #default_value to theme_get_setting('your_option'), which tells Drupal to look for this setting in the database. But here's the brilliant part -- if it can't find that setting in the database, it will check in your theme's .info file! So add this line:

settings[your_option] = 1

Now your theme will use the default setting unless the admin overrides it on the theme settings page.

You'll want to actually do something with this setting, so here's the PHP call to load it.

theme_get_setting('your_option');

You can call this in from any of your .tpl.php files. For a simple checkbox option like this, you can build an if() statement around it, like so:

<?php if (theme_get_setting('your_option')): ?>
  <!-- Your code here! -->
<?php endif; ?>

In this example, we added a checkbox, but you can add just about any form elements you can think of, including radio buttons and text input fields. What sort of options will you add to your theme?

References

Comments

Posted by Chris Yakimov on . [Reply]

Thanks Scott - don't have any immediate need for Drupal, but this is so clear and nicely explained, it has me excited to get a project. :) Cheers

Chris (yakker - drupal.org)

Posted by Anja on . [Reply]

Does this actually work for you? I'm trying to add a text field to a Drupal 7 theme but nothing's coming out on the theme's setting page and I also don't have any output on the site, even though I set a default value in the theme's info file. So the problem is probably in theme-settings.info and I'm not too sure about the syntax there. Yours is different from the one in http://drupal.org/update/theme/6/7#theme-settings, and the one over there has a mistake in it (I think - using caberet instead of foo once). Also not sure about PHP tags - opening and closing, just opening? I have cleared caches btw.

scott's picture

Posted by Scott Vandehey on . [Reply]

Yeah, it is working for me. Without seeing your source, I couldn't tell you what's wrong - feel free to email me (scott at metaltoad).

One thing to check is make sure the function includes your theme's name, and another is that you're using the same setting name throughout.

We'll be posting a new theme very soon which includes this technique.

As for PHP tags, you only need the opening tag in theme-settings.php, but it won't hurt to add the closing tag. One of our programmers explained why to me once, and I forget the logic, but basically if it's a stright PHP file, you don't need the closing tag.

Posted by Anja on . [Reply]

Oh yeah. I was doing everything right. Except I named the file theme-settings.tpl.php instead of theme-settings.php. And that was the only place I didn't check a million times for mistakes :) Thanks!

Posted by Mo on . [Reply]

>In D6, this was kind of a pain, because you had to write all sorts of functions to save and load your settings to the database and handle everything properly.

This is not correct: this work the same in D6. Look in system.admin.inc, line 506.

scott's picture

Posted by Scott Vandehey on . [Reply]

Sorry if I explained it poorly - I'm not a programmer, so this is all Greek to me. However, this page makes it clear that D7 expands the abilities available to themes: "This gives the same power to themes that modules have if they use hook_form_system_theme_settings_alter()." As it was explained to me, that mostly meant that in D7, the form API automatically handles some things like saving your settings.

Posted by madaerodog on . [Reply]

I used it successfully in theme-settings.php altering the 3 available groups theme_settings, logo, favicon.

What if I want to create another custom group in the theme settings page? How can I achieve that? add another form under the 3 instead of altering one

Posted by Levi on . [Reply]

When I first started working with Drupal everything was hard. It was much more customizable than any other similar platform but in the same time very basic things would take time to accomplish. In the new version it seems that Drupal, as a blogging platform, has now surpassed the functionality which paid Wordpress themes like Thesis have. It's really cool!

Posted by Antonio on . [Reply]

Is there any way you can tell how to add (for example) secondary logo in theme? I cant find anywhere how to do that in Drupal 7.

Thanks.

Posted by Eugen on . [Reply]

Hmm, how I can check whether the form was sent before load the page after send?

This code not working :( -->

function themename_settings_submit($form, &$form_state) {
  $settings = array();
 
  // Check for a new uploaded file, and use that if available.
  if ($file = file_save_upload('sublogo_upload')) {
    $parts = pathinfo($file->filename);
    $destination = 'public://' . $parts['basename'];
    $file->status = FILE_STATUS_PERMANENT;
 
 
     if (file_copy($file, $destination, FILE_EXISTS_REPLACE)) {
        $_POST['sublogo_path'] = $form_state['values']['sublogo_path'] = $destination;
     }
  }
 
}

Posted by Dr. Robert Doebler on . [Reply]

True. It is such a hassle when you're not sure what you're doing. Anyway, his is great, more theme options the better. I love to tinker around with Drupal once in a while even though it's a bit more complicated than other platforms. Thanks for sharing your code!

Posted by ben hamelin on . [Reply]

Sweet, thanks! I was actually looking to do the reverse of this post, which was to REMOVE specific theme settings. This post got me headed in the right direction, and with some $form['theme'] = NULL; statements I was off and running! Thanks folks!

Add new comment