Genesis Explained Option Functions

In the last post in the Genesis Explained series I explained the image functions for Genesis. In this post I’ll be going through the genesis/lib/functions/options.php file. There are technically 7 functions in the file, but one is part of a filter and half the remaining values really just echo the “get” value for you, so it really makes for 3 functions to learn.

Here is the full list of functions

• genesis_get_option
• genesis_option
• genesis_get_seo_option
• genesis_seo_option
• genesis_custom_field
• genesis_get_custom_field
• genesis_get_term_filter

The first 4 functions deal with theme options and are really some version of genesis_get_option. The last function is part of a filter.

genesis_get_option($key, $setting = null)

This function has two possible args. The first, $key, is required. This value indicates which option value to return. For example, if I want to see if the Show Primary Navigation box has been checked I would use “nav” as my key value. You can look in the genesis/lib/admin/theme-settings.php file for all the built in options.

The $setting value is optional. If it is not defined it will look in the GENESIS_SETTINGS_FIELD. You can also use GENESIS_SEO_SETTINGS_FIELD for other built in settings, but those settings can be retrieved more easily with another function, which we’ll talk about in a minute. You even have the option of creating your own setting field and retrieving that with this function.

I’ll be talking about this in more detail later, including how to add your own options, but for now, lets look at one of the option lines to see how to find the option.

<p><input type="checkbox" name="<?php echo GENESIS_SETTINGS_FIELD; ?>[nav]" id="<?php echo GENESIS_SETTINGS_FIELD; ?>[nav]" value="1" <?php checked(1, genesis_get_option('nav')); ?> /> <label for="<?php echo GENESIS_SETTINGS_FIELD; ?>[nav]"><?php _e("Include Primary Navigation Menu?", 'genesis'); ?></label>
	</p>

See the name attribute, that’s where you want to look. in this case it has “GENESIS_SETTINGS_FIELD” so you know what field is being used, and since the function uses that as a default you don’t need to specific the $setting. The next part is [nav] and that is your $key. So if you want to retrieve the theme option for displaying the navigation use

$displayNav = genesis_get_option( 'nav' );

You can filter the option with “genesis_pre_get_option_’.$key”, the $key value means that you can specify which key you are filtering, so if you are trying to change the nav option, you would use

add_filter( 'genesis_pre_get_option_nav', 'child_get_option_nav' );

Then you can write a function “child_get_option_nav()” that returns a different value in different circumstances.

Another filter comes just before the value is returned. genesis_options lets you filter what is being returned. You could use a preg_replace or str_replace to change teh returned values after the have been retrieved from the database. genesis_pre_get_option_$key won’t work for that since it returns whatever value you provide instead of checking the database.

genesis_option() is exactly the same except it echos the value.

genesis_get_seo_option($key)

This function works mostly the same as genesis_get_option, except it provides the GENESIS_SEO_SETTINGS_FIELD $setting value to the genesis_get_option function. That saves a bit of code if you are trying to get a SEO setting value. genesis_seo_option() just echos the value returned by genesis_get_seo_option().

genesis_get_custom_field($field)

This is another Genesis function that simplifies a WordPress function. As you can see there is only one arg, $field. This is required and is the custom field name you wish to retrieve. The genesis_custom_field() function echos this value automatically.

To retrieve a custom field inside a Genesis action function you would need this using the WordPress function

add_action( 'genesis_post_content', 'child_custom_field' );
function child_custom_field() {
    global $post;

    $myField = get_post_meta( $post->ID, 'field_name', true );

    echo $myField;
}

Using Genesis functions you could simplify that to

add_action( 'genesis_post_content', 'child_custom_field' );
function child_custom_field() {
    genesis_custom_field( 'field_name' );
}

There are times you wouldn’t use this function. It won’t work with array values, so if you have multiple fields with the same name you need to use WordPress functions to retrieve an object (array) that you can then convert into strings you will be able to output. The function also has some built in safety checks that can prevent some code from working right. It runs the stripslashes() function and wp_kses_decode_entities() function before returning a value. Most of the time this isn’t an issue, and the genesis_get_custom_field() function is a huge time saver.

That pretty much wraps up the option functions. Next time I’ll be going through genesis/lib/functions/widgetize.php and wrapping up the Functions subseries. After that I have two more parts planned in the Genesis Explained series, a look at the admin system which will cover the theme options and post/term meta followed by a look at the style sheet. If you don’t want to miss that please subscribe to the feed or put your email address in the sidebar to have it delivered to your mail.

Once this series is done I’ll be starting work on the Child Theme Creation series, so please add your ideas to the Wish List.