Adding settings for you product is usually a necessary part of creating a distributable package. Here’s a guide on how to add settings to your product before you export it.

Enabling Debug Mode

To enable debug mode, simply add the following line to the top of your includes/config.php. This setting is not recommended for production environments.

$config['Misc']['debug'] = true;

Now navigate to your Settings -> Options page in admincp. You’ll notice some new “Developer” options, including “Add New Settings Group”. This will let you create a new setting group and assign it to a product. When you open up this new Setting Group you’ll notice an Add Setting link in the setting group title bar to add individual settings to that group. Here’s the options you can set:

  • Varname: This is the name you’ll use to call your setting out programmatically using $vbulletin->options[] in a plugin or {vb:raw vboptions} in a template. I usually stick to a productname_fieldname naming convention.
  • Setting Group: If you clicked the “Add Setting” link from within your new setting group this should already be on the correct value. If not you can change it here.
  • Title: A phrase to be used as the title in the admin menu.
  • Description: A phrase to be used as the description in the admin menu.
  • Option Code: This is an option for how you want this particular setting to display in the admin menu. A blank value is usually sufficient, though a value of “textarea” renders as a textarea rather than a single-line text input, a “yesno” value will render “Yes” and “No” radio buttons, or you can enter custom display code. See below for an example.
  • Default: The default value.
  • Data Validation Type: This allows you to select from a set list of data types the form expects to receive when this field is submitted.
  • Validation PHP Code: Allows you to enter custom validation rules for this fields. More on this below.
  • Display Order: The numerical value of display order within this settinggroup.
  • Blacklist: This determines whether or not the value should be backed up when admin settings are backed up. Blacklisted fields are skipped in the backup process.
  • vBulletin Default: This determines whether or not the field will be reset during upgrade scripts. You’ll likely want to set this to “No” for any additional fields if you want the values to persist through any upgrades.
Retrieving settings in your code

To retrieve a setting, simply call it as I briefly mentioned above. For example, this plugin script would print the admin setting with the Varname “productname_fieldname”.

echo $vbulletin->options['productname_fieldname'];

Or you can use them as variables in your template files. Here’s a field value wrapped in a header tab.

<h1>{vb:raw vboptions.productname_fieldname}</h1>
Custom Option Code Display

You may run into a situation where you want a setting input to display in a method not supported by the standard options. A <select> tag is a great example of this. The Option Code option natively supports some workarounds for this. First, you can specify select:piped followed by a list of select values. Here’s an example of how the disable_ajax field in vBulletin’s General Settings accomplishes this:

select:piped
0|enable_all_ajax_features
1|disable_problematic_ajax_features
2|disable_all_ajax_features

These values are all accompanied by entries in the @[email protected] table with a fieldname of cpoption and a varname corresponding to the value entered for the select option (e.g. enable_all_ajax_features).

Another method is to specify the actual HTML to be rendered to the page for the inputs. An example of this is the sitemap_priority setting in the XML Sitemap setting group.

" . vb_number_format('0.0', 1) . "
" . vb_number_format('0.1', 1) . "
" . vb_number_format('0.2', 1) . "
" . vb_number_format('0.3', 1) . "
" . vb_number_format('0.4', 1) . "
" . vb_number_format('0.5', 1) . "
" . vb_number_format('0.6', 1) . "
" . vb_number_format('0.7', 1) . "
" . vb_number_format('0.8', 1) . "
" . vb_number_format('0.9', 1) . "
" . vb_number_format('1.0', 1) . "

The thing to keep in mind here is that the value you insert will be used in a php script between two double-quotes. Therefore, it’s necessary to escape any double quotes you want to use with a backslash (\). It also means, however, that you can break the string and insert values accessible from php variables and functions. Just remember to start the string back up with another double-quote. You can access data corresponding to the current setting using the $setting array, as shown above.

Custom Validation PHP Code

This one is pretty straightforward. You simply need to write a php script to return true or false based on the $data variable. This example is from the thumbcolor setting in the Message Attachment Options and validates that the data is in hex color code format. The preg_match function returns the number of times the regex pattern occurs in a string, so here its testing whether or not that value is greater than 0.

return (preg_match('~^#([0-9A-F]{6})$~i', $data) > 0);

Share this article:

If this resonates with you I'd love to help!

I help business with problems like these every day.

Click below to schedule a call.

About The Author

Bryce Hamrick

Facebook Twitter

Bryce Hamrick is an entrepreneur, business & marketing strategist, and product consultant with nearly two decades of experience in industry. Bryce has been a software engineer, product manager, and director of product management for startups as well as large enterprises. He has led teams to bring dozens of products to market and has executed numerous six-figure product launches. Today Bryce and his team focus on leveraging his product execution strategy to help businesses with growth and scale.