Docs Getting started with Titan Framework

This is a quick rundown of all the steps you need to do in order to use the features of Titan Framework. After you finish with this article, you will be able to add and get options from your admin with only a few lines of code. We will be creating options for a WordPress theme in this article (the steps are identical for a plugin).

---

TLDR Version

1. Download & activate the Titan Framework Plugin, OR embed Titan Framework into your project.
2. Use the tf_create_options hook
3. Do a $titan = TitanFramework::getInstance( 'my-theme' ) to create an instance of TF
4. Use the function $titan->createAdminPanel to create your admin panels
5. Use the function $panel->createOption to create your options

---

Full Version

Step 1: Download the Titan Framework plugin

Before anything else we first need to download and activate the Titan Framework plugin. Download the plugin from the WordPress plugin repository using the button below. Install and activate it in your WordPress development site afterwards.

Step 2: Including Titan Framework

There are 2 ways to include Titan Framework into your project. First is by using it as a plugin; second is by embedding it in your project.

• Use it as a plugin if you are creating a theme, or large plugins.
• Embed it if you are creating a very small plugin.

Either methods will work, whether you use the Titan Framework for developing WordPress themes or for WordPress plugins. The codes for including the framework are the same across themes and plugins.

Step 2a. Use the plugin

When the Titan Framework plugin is activated, then we can already use the framework functions in our code. However, if the plugin is not activated, then our options won’t show up and errors might show up.

We can display an administration notice in the backend regarding the need to activate Titan Framework along with a link to install the framework from the WordPress plugin repository.

1. Copy the script named titan-framework-checker.php from the Titan Framework codebase into your project.

2. Afterwards, insert this code in your functions.php or your main plugin script:

   require_once( 'titan-framework-checker.php' );

Step 2b. Embed the Framework

When you want to make your project independent from plugins, you might want to embed Titan into your project. When you embed Titan, you’ll no longer need to activate the Titan Framework plugin for your theme or plugin to work.

However, one caveat would be that since the framework is embedded, updates and bug fixes to the framework won’t be available. You would have to be the one to push out updates to your project if you need to update the embedded framework.

1. Create a folder named titan-framework in your project and put all the framework code there. (important: the PHP scripts should be inside the titan-framework folder)
2. Afterwards, in your functions.php or your main plugin script, add the code below:

require_once( 'titan-framework/titan-framework-embedder.php' );

NOTE: If you are still using the old detection method, please upgrade to the method described above. It will prevent future problems in framework detection.

TIP: Use the framework as a plugin as much as possible

Step 3: The Create Options Hook

All the initialization and creation code for your options need to be inside a special hook for Titan Framework called tf_create_options. Here’s how you use it:

add_action( 'tf_create_options', 'my_theme_create_options' );
function my_theme_create_options() {
    // Initialize Titan & options here
}

You can also use it inside a class structure:

class MyClass {
    function __construct() {
        add_action( 'tf_create_options', array( $this, 'createMyOptions' ) );
    }

    function createMyOptions() {
        // Initialize Titan & options here
    }
}
new MyClass();

The tf_create_options action is called early during the after_setup_theme action (specifically priority 5). This will not work if you add this action into later running hooks like admin_init, init, or wp_head.

Step 4: Getting an Instance of Titan Framework

From this point forward we will be using the classes and functions provided by Titan Framework. Along with the creation of options, the framework also enables us to easily create admin menus, pages and tabs.

First we need to ask for an instance of the framework. Think of this step as telling the framework that what we’re about to do is for our theme (or plugin). This is important so that all the options that we create won’t get mixed up with options created by other plugins.

Add this line at the start of your call to the tf_create_options hook:

$titan = TitanFramework::getInstance( 'my-theme' );

Step 5: Creating Our Admin Page & Menu

Using our framework instance under the $titan variable, let’s create the admin page that would contain all of the settings of our theme. We would also be creating an admin menu that will be used to access our settings. Let’s name name our menu Theme Options

$panel = $titan->createAdminPanel( array(
    'name' => 'Theme Options',
) );

Step 6: Creating Admin Options

Now on to the fun part – creating options. Creating an option is as simple as calling a single function similar to the previous step.

We will be putting our options inside our newly created admin page by using the $panel variable which we also just created. Let’s create a text input, a select drop down box and a save button. After you put in the code below, open your WordPress admin and head over to the admin page we created for Theme Options.

$panel->createOption( array(
    'name' => 'My Text Option',
    'id' => 'my_text_option',
    'type' => 'text',
    'desc' => 'This is our option'
) );

$panel->createOption( array(
    'name' => 'My Select Option',
    'id' => 'my_select_option',
    'type' => 'select',
    'options' => array(
        '1' => 'Option one',
        '2' => 'Option two',
        '3' => 'Option three',
    ),
    'desc' => 'This is a select drop down box',
    'default' => '2',
) );

$panel->createOption( array(
    'type' => 'save'
) );

So Far: Option Creation Summary

Okay so now we have created our admin panel named Theme Options along with a few options. Here’s the summarized code that you should have come up with by going from step 1 to step 6.

// Check whether the Titan Framework plugin is activated, and notify if it isn't
require_once( 'titan-framework-checker.php' );
add_action( 'tf_create_options', 'my_theme_create_options' );

function my_theme_create_options() {
    // Initialize Titan with my special unique namespace
    $titan = TitanFramework::getInstance( 'my-theme' );

    // Create my admin panel
    $panel = $titan->createAdminPanel( array(
        'name' => 'Theme Options',
    ) );

    // Create options for my admin panel
    $panel->createOption( array(
        'name' => 'My Text Option',
        'id' => 'my_text_option',
        'type' => 'text',
        'desc' => 'This is our option'
    ) );

    $panel->createOption( array(
        'name' => 'My Select Option',
        'id' => 'my_select_option',
        'type' => 'select',
        'options' => array(
            '1' => 'Option one',
            '2' => 'Option two',
            '3' => 'Option three',
        ),
        'desc' => 'This is a select drop down box',
        'default' => '2',
    ) );

    $panel->createOption( array(
        'type' => 'save'
    ) );
}

Step 7: Getting Saved Option Values

We’re done with the admin part. Your users can now save (and reset) the options we just created. Now we need a way to get the saved values so we can use it in our theme or plugin. We can get the values with just one function call. You can only call getOption during or after the after_setup_theme hook (priority 10, the default) or within a theme’s template script.

add_action( 'after_setup_theme', 'myFunction' );
function myFunction() {
    $titan = TitanFramework::getInstance( 'my-theme' );
    $myTextOption = $titan->getOption( 'my_text_option' );
    $mySelectOption = $titan->getOption( 'my_select_option' );
    // Do stuff here
}

You can read more about getting option values in Getting Option Values

What’s Next? Creating Tabs, Meta Boxes & Theme Customizer Sections

Now that you know how to create admin pages and put options inside them. You can go on and create tabs, meta boxes and theme customizer sections for your project. The method of creating options is the same for everything:

$titan = TitanFramework::getInstance( 'my-theme' );

/* 
 * Creating a meta box
 */
$myMetaBox = $titan->createMetaBox( array(
    'name' => 'My Meta Box',
) );

Create your options the same way as above using $myMetaBox

/* 
 * Creating a theme customizer section
 */
$mySection = $titan->createThemeCustomizerSection( array(
    'name' => 'My Section',
) );

Create your options the same way as above using $mySection

/*
 * Creating an admin page tab
 */
$panel = $titan->createAdminPanel( array(
    'name' => 'Theme Options',
) );

$myTab = $panel->createTab( array(
    'name' => 'General Tab',
) );

Create your options the same way as above using $myTab Getting your saved options are the same no matter whether the option is in a meta box or the theme customizer. All options can be acquired by:

// Getting an admin option
$value = $titan->getOption( 'my_option_name' );

// Getting a theme customizer option
$value = $titan->getOption( 'my_option_name' );

// Getting a meta box option
$value = $titan->getOption( 'my_option_name' );