Docs_appliance_core_help

beingzoe edited this page Feb 2, 2011 · 4 revisions

Appliance: Marketing: JIT (Just-in-Time) Sidebar

Widget! Drop this widget in your sidebar above the last couple things in a sidebar and they will magically float with the page once they are scrolled to the top. Perfect for important navigation or “promotional” call to action content.


Usage Summary

$my_theme->load('jit_sidebar');

Then just add the widget to the appropriate sidebar just above the items you wish to “float”.


Usage Notes

Requires jQuery. Does not work in IE6.

The script will not trigger the floating if it detects that the height of the items being floated is taller than the height of the current browser viewport. Otherwise there would be content that would never be reachable.


Roadmap Notes

There are issues in certain layouts where the floating JIT sidebar overlaps the site footer in an unattractive way. This will be improved to prevent that from happening.

Clone this wiki locally

Appliance: Core: Help

Extend the built-in help files/system with your own custom help. Blog/Site owners should never wonder how to use your stuff again!

When a kitchen adds help content (loads the ‘help’ appliance) or adds any appliance that has help content (all the bundled appliances do) a new top level ‘Theme Help’ menu section will be added to the Admin Sidebar.


Usage Summary


$help_array = array (
        array (
            'page' => 'Features',
            'section' => 'Blinking',
            'title' => 'The BLINK Tag',
            'content_source' => 'some_valid_callback'
        ),
        array (
            'page' => 'Features',
            'section' => 'Content Slideshows',
            'title' => 'Appliance: Media: Tools Scrollable',
            'content_source' => array('KST_Appliance_Asides', 'helpBlogAsides')
        ),
        array (
            'page' => 'WordPress',
            'section' => 'Blog Posts',
            'title' => 'How To Click the Publish Button',
            'content_source' => 'Click the blue button that says publish. Any content directly input will be output.'
        ),
        array (
            'page' => 'Custom Theme Page',
            'section' => 'That Feature I Made For You',
            'title' => 'Step 1',
            'content_source' => '/abs/path/to/file.php'
        )
    );

$my_kitchen->load('help');
$my_kitchen->help->add($help_array);

This example created (4) new help entries on 3 different pages. One of those pages was a completely random/custom page made up on the fly.

Notice that you can manage and add your help anyway you like:

  • Callback
  • Included file
  • Any valid html string directly


Method Reference

  • add()

We like to keep things simple ;)

add()

Tell KST/WordPress that you want to add some help files. Load as many entries as you like in one array and one add() call, or do ’em all separate if you like.

Usage
$my_kitchen->help->add($help_files);

Parameters

  • $help_files
    An indexed array containing an associative array for each help ENTRY:
    • page => ‘Page Name appearing in menu and on page’
    • section => ‘Section Name as it will appear in Table of Contents and as an h2’
    • ‘title’ => ‘Title of your entry in that section’
    • ’content_source => valid_callback | /path/to/file.php | $string_content

And that’s it. Each entry is merged in with all other help entries and output as needed.

Examples


// Add Help
$appliance_help = array (
        array (
            'page' => 'WordPress',
            'section' => 'Special Formatting',
            'title' => 'Appliance: Media: Asides',
            'content_source' => array('KST_Appliance_Asides', 'helpBlogAsides')
        )
    );
$my_kitchen->load('help');
$my_kitchen->help->add($appliance_help);

function someHelpEntry() {
    ?>
        <p>This is my callback entry</p>
    <?php
}

$current_help_path = get_template_directory() . '/help/';
$help1 = array(
        array (
            'title' => 'Intro to WP1',
            'page' => 'WordPress',
            'section' => 'Post thumbnails',
            'content_source' => $current_help_path . 'test.php'
            ),
        array (
            'title' => 'loving WP2',
            'page' => 'WordPress',
            'section' => 'Another section',
            'content_source' => $current_help_path . 'test.php'
            ),
        array (
            'title' => 'Intro to WP3',
            'page' => 'WordPress',
            'section' => 'Post thumbnails',
            'content_source' => $current_help_path . 'test.php'
            ),
        array (
            'title' => 'loving WP4',
            'page' => 'WordPress',
            'section' => 'Another section',
            'content_source' => $current_help_path . 'test.php'
            ),
        array (
            'title' => 'Intro to WP5',
            'page' => 'WordPress',
            'section' => 'Post thumbnails',
            'content_source' => 'someHelpEntry'
            ),
        array (
            'title' => 'loving WP6',
            'page' => 'WordPress',
            'section' => 'Another section',
            'content_source' => "<p>Just some content...!</p>"
            ),
        array (
            'title' => 'Excerpts and teasers',
            'page' => 'WordPress',
            'section' => 'Using Blog Posts',
            'content_source' => $current_help_path . 'test.php'
            ),
        array (
            'title' => 'Excerpts and teasers',
            'page' => 'WordPress',
            'section' => 'Using Blog Posts',
            'content_source' => "<p>THEME1 Excerpts and teasers</p>"
            ),
        array (
            'title' => 'Excerpts and teasers',
            'page' => 'WordPress',
            'section' => 'Using Blog Posts',
            'content_source' => 'someHelpEntry'
            ),
        array (
            'title' => 'Excerpts and teasers',
            'page' => 'WordPress',
            'section' => 'Using Blog Posts',
            'content_source' => "<p>THEME3 Excerpts and teasers (there is also a callback before this #2)</p>"
            ),
        array (
            'title' => 'Sociable',
            'page' => 'Features',
            'section' => 'Using Sociable',
            'content_source' => $current_help_path . 'test.php'
            ),
        array (
            'title' => 'Adding new images sizes for posts',
            'page' => 'Features',
            'section' => 'Additional Image Sizes',
            'content_source' => $current_help_path . 'test.php'
            )
    );

// Add help files
$my_theme->help->add($help1);

You’ll note in this example (an early test of the system) that there are entries that will overwrite each other. There can only be one entry per Page>Section>Title. Duplicating and reusing Pages and Sections is highly encouraged. Duplicating titles is death. However it is an intended function. The goal is to allow Themes to overwrite core entries and for plugins to overwrite Theme entries. The theory here is that Themes modify KST and Plugins modify Themes.



// Add Help
$appliance_help = array (
        array (
            'page' => 'Marketing',
            'section' => 'SEO, Meta Data, and Analytics',
            'title' => 'SEO',
            'content_source' => array('KST_Appliance_Seo', 'helpSeoSeo')
        ),
        array (
            'page' => 'Marketing',
            'section' => 'SEO, Meta Data, and Analytics',
            'title' => 'Analytics',
            'content_source' => array('KST_Appliance_Seo', 'helpSeoAnalytics')
        ),
        array (
            'page' => 'Marketing',
            'section' => 'SEO, Meta Data, and Analytics',
            'title' => 'Other Meta Data',
            'content_source' => array('KST_Appliance_Seo', 'helpSeoOtherMetaData')
        ),
        array (
            'page' => 'Marketing',
            'section' => 'Microformats',
            'title' => 'Sitewide vCard (Microformat)',
            'content_source' => array('KST_Appliance_Seo', 'helpSeoMicroformatVcard')
        )

    );

$my_kitchen->load('help');
$my_kitchen->help->add($appliance_help);

class KST_Appliance_Seo extends KST_Appliance {

    ...the actual class methods...then...
    
    /**
     * KST_Appliance_Help entry
     * SEO: SEO
     *
     * @since       0.1
    */
    public static function helpSeoSeo() {
        ?>
    
            <p>
            Your theme has built-in control over the page title and meta tags throughout your site.
            BE SURE to set the GLOBAL DEFAULTS for SEO settings on the "Theme Options &gt; <a href="admi...
            where you will also find context specific help for SEO and meta data.
            </p>
    
            <h3 id="seo_post_page_custom_fields">SEO per Post/Page</h3>
    
            <p>Directly below the editor while adding/updating posts and pages you will see a metabox for e...
    
            <ol>
                <li>Page Title</li>
                <li>Meta Keywords</li>
                <li>Add TAGS to Meta Keywords (post tags + global)</li>
                <li>Add Global Keywords to Meta Keywords (these + global)</li>
                <li>Meta Description</li>
            </ol>
    
            <p><strong>How the the page title is created</strong></p>
            <ol>
                <li>
                    Uses custom field "Page Title" if it exists for that post and page
                    (except the home, blog index, archives, search, and 404) appending "Blog Name" (Sett...
                </li>
                <li>
                    Otherwise the page title is created dynamically depending on the type of page is being viewed
                    using the post/page entry title where available in conjunction with relevant crit...
                     appending "Blog Name" (Settings &gt; General) depending on your  in "Appearance &gt; Theme Options".
                </li>
            </ol>
            <p><strong>How meta keywords/description is created</strong></p>
            <ol>
                <li>
                    Uses custom field "Meta Keywords" or "Meta Description" if it exists for all posts and pages
                    (except the home, blog index, archives, search, and 404).
                    <ol>
                        <li>For keywords: If Add TAGS is checked the tags for that post/page are appended on outp...
                        <li>For keywords: If Add Global Keywords is checked the post/page default keywords are app...
                    </ol>
                </li>
                <li>
                    If no custom field exists the theme attempts to use the appropriate post/page specifc defaults enter...
                </li>
                <li>
                    If no post/page specific default exists the theme attempts to use the global defaults entered in ...
                </li>
                <li>
                    If no global default exists then the theme uses "Blog Name" and "Tagline" under SETTINGS &gt; GE...
                </li>
            </ol>
            <p>
                The Home, Blog index, Archives, Search, and 404 pages cannot use the custom fields for the meta ...
            </p>
            <p>
                <strong>Note:</strong> The built-in "appliances" (embedded plugins) essentially precludes the need t...
                <em>If for some reason you wish to not use the built-in SEO or Google Analytics options there is n...
                You should be able to safely ignore and leave blank any of these built-in theme options. <br />...
                and experience problems or are optimizing simply edit functions.php and comment out the line...
            </p>
            <p><small>Applies to Kitchen Sink HTML5 Base bundled SEO</small></p>
        <?php
    }
    
    
    /**
     * KST_Appliance_Help entry
     * SEO: SEO
     *
     * @since       0.1
    */
    public static function helpSeoAnalytics() {
        ?>
            <p>If you enter your Google Analytics Tracking ID in "Theme Options" the Google Analytics tracking...
            <p><small>Applies to Kitchen Sink HTML5 Base bundled SEO</small></p>
        <?php
    }
    
    
    /**
     * KST_Appliance_Help entry
     * SEO: SEO
     *
     * @since       0.1
    */
    public static function helpSeoMicroformatVcard() {
        ?>
            <p>Microfomats help bots index your content and more and more are becoming int...
            <p>
                At some point we will be adding the full range of microformat options. For...
                to use hCard specifications in general (like the list of posts in the blog...
                also set some contact info about you or your organization in the SEO setti...
                will be added at the bottom of every page. When someone browsing your site...
                (or bots) they will be able to add the vCard info to their contacts automa...
            </p>
        <?php
    }

}