BioShip Documentation

BioShip QuickStart

Even though BioShip has a lot to it, getting started with BioShip is actually easy. The main thing to remember is you do not need to setup and use every single feature! For the majority of projects the default settings for many of the options are great. So the fastest way to get started is to leave them alone and focus on your design.

Practically speaking, this means customizing the Skin layer settings mostly, and adjusting some Skeleton layer sidebar settings if you need to modify your sidebars. Most of the Skeleton and all of the Muscle layer settings can be left for later.

BioShip has a lot of complex code under the hood to make everything super-flexible. This means you can leave the more advanced stuff for if and when you actually need it, confident and relaxed knowing that you really can change anything at all in the future. And in the meantime, enjoy the simplicity of having everything setup and working sooner!

And if and when you are ready to delve deeper, complete documentation is available below. I hope you enjoy using BioShip and welcome any feedback or improvements.

BioShip Installation

Basic Install

Preview Install

Theme Updates

Manual Theme Update

Optimization

BioShip Child Theming

Setting up a Child Theme using the BioShip Theme Framework as your Parent Theme is very easy and highly recommended for best practice development. The main reason being as with any Child Theme you can keep the Parent Theme Framework updated (allowing for improvements and fixes to the Framework to easily be installed) without losing your own file customizations and functions. As most websites require some kind of customization of this kind, being able to add and modify your Child Theme functions.php is the most basic of features that a Parent Theme should support.

One-Click Child Theme Install

To make it even easier, BioShip has One-click Creation for Child Themes, so you can get customizing as soon as possible. Plus, BioShip auto-transfers your current Parent Theme Setting to your Child Theme when you first activate your it, so there is no need to set the same settings again if you are moving from using BioShip as a standalone Theme to using a Child Theme.

Visit your Theme Options page under the Wordpress admin Appearance menu. Enter a new Child Theme display name in the box to the right of the layer tabs and click Create Child Theme. The next page will show the creation result in the same space. Click the activate link there and you are now running your new Child Theme!

Manual Child Theme Install

Preview Child Theme Install

In this way you can create a new Child Theme skin for your site and activate it once you are satisfied with the new design result. Again, generally speaking, if you are the sole site admin of the site then option 2a is fine, otherwise you might want to go with 2b so that other site admins aren't confused by seeing the new in theme preview while you're developing with it.

Cloning Child Themes

You can also clone any existing Child Theme with one click at the top right of the Theme Options page for that Child Theme. This allows you to easily 'fork' an existing Child Theme for further development without affecting the live site display. All files and theme settings will be automatically copied to the new clone Child Theme directory on form submission. You can then activate the new Child Theme at any point from the Appearance > Themes page.

BioShip Frameworks

Theme Options Frameworks

WordPress Customizer

BioShip supports the in-built WordPress Customizer for all Theme Options with Live Preview updates via the Customizer API. The Customizer gives you a sidebar panel with Theme Settings and a live preview window that is updated by javascript or refresh. Bioship implements some custom controls by using the Kirki Library in combination with it's own theme options array. You will also see some extra panel controls have been added for the Customizer to control sidebar width and position. If you find the Customizer interface restrictive is it recommended you use the Titan Framework admin page instead.

WordPress.Org Compliance

Titan Framework

Titan provides a great modern user interface for modifying all available Theme Settings for BioShip in the one place. There is a wide variety of controls available via Titan, however only a small number are used to reduce complexity. Note: admin page output is changed for BioShip so that all tabs are available on the one pageload (like Options Framework.)
Reference: Titan Framework Documentation.
[Theme Settings option_name key: child-theme-slug_options]

Options Framework

BioShip Theme Options were originally handled by the Options Framework, which is still supported but no longer default. While there are some minor differences between the Titan and Options Framework, they are very similar in operation.
Reference: Options Framework Documentation.
[Theme Settings option_name key: child_theme_slug]

v1.5.0+ Upgrade Notice

Since Titan if now used by default after v1.5.0, if you are upgrading from that, use one of the two options given below, either to switch back to Options Framework or to transfer your existing theme settings to the Titan Framework format.
"; $html .= "

Framework Switching

To use Options instead of Titan, create an option name 'theme-slug_framework' and the value of 'options' Alternatively, you can create a file in your desired theme directory called titanswitch.off and if you wish to switch back to using Titan again, create a file called titanswitch.on If either of these files is created it will change the above options value and then delete the file. After switching between these Frameworks you will want to review your theme settings and resave.

Transferring Settings

To transfer settings from one framework to another you can use the above querystring on an admin URL (when logged in as administrator or with edit_theme_options capability.) This is helpful when converting theme settings from Options Framework usage to using Titan Framework instead. After doing the transfer and switching to the Titan Framework, be sure to check your settings (especially fonts) on the Theme Options page and save them again to remove again discrepencies.

The totheme parameter is optional, if left out it will transfer settings to your current active theme. Note: Currently only supports transferring existing theme settings TO Titan from Options Framework. as code is needed for image URLs from Options Framework to be inserted in the media library for Titan, and development will be moving forward with Titan rather than Options Framework.)

Copying Theme Settings

To copy theme settings between any two existing themes using the above query string on an admin URL (when logged in as administrator or with edit_theme_options capability.) This may be helpful if you created a Child Theme and the theme settings failed to transfer from the Parent Theme. Or if you simply wish to copy theme settings between themes for some other reason.

Other Frameworks

Hybrid Core

Hybrid Core is activated via Theme Options -> Skeleton -> Hybrid tab.
Note: for consistency, Hybrid Content Template Hierarchy and attributes are implemented regardless of this.

Hybrid Hook

All hook positions are automatically made available to the Hybrid Hook plugin (modified for BioShip.) When activated (via Theme Options -> Skeleton -> Hybrid) you can access Appearance -> Hybrid Hook. This allows you to easily add content (Text, HTML or Shortcode) to any of the Layout Hook section positions. (You can also specify a priority if you need to insert between existing hooked functions.) see the Layout Hook Guide for a detailed hook reference.

Foundation

Foundation by Zurb loading is activated via Theme Options -> Skeleton -> Foundation tab."; // TODO: add more extensive information on Foundation here... $html .= "

BioShip Extensions

BioShip Theme Options

SKIN

".strtoupper($layer)."

".strtoupper($layer)."

".$option['name']."

BioShip Theme Metabox

You will find a Theme Settings Metabox on the Writing Screen (above the Publish box) which allows you to override default display and other settings on a per-post (or per-page) basis, giving you more fine-grained control over many of the page elements (without having to resort to other more complex workarounds to achieve the same effect, such as one-column templates, hiding elements with styles and endless page-targeted CSS rules that clutter your stylesheets etc.)

These Metabox override settings take priority over filtered theme settings. (ie. Settings -> Filters -> Overrides) Currently most override options in the metabox are for display (hiding elements) rather than output (removing them.) When set, CSS style rules (with !important) are added to that page to achieve the desired effect.
[Display Overrides post meta key _bioship_display_overrides (pre-2.1.0: _displayoverrides)]
[Templating Overrides post meta key _bioship_templating_overrides (pre-2.1.0: _templatingoverrides)]

Content Override Tab

Thumbnail / Featured Image

Content Display Overrides

Content Filters

BioShip provides an easy way to turn off some in-built WordPress content filters on a post/page basis via the metabox. This can be handy if they are mangling your content for a particular post for some reason and you want an easy fix. Currently available filters you can disable are: wpautop, wptexturize, convert_smilies, convert_chars
[Filter Overrides post meta key: _bioship_removefilters (pre-2.1.0: _disablefilters)]

Layout Override Tab

General Layout

Navigation

Sidebar Override Tab

Sidebar Output Overrides

Sidebar Display Overrides

PerPost Styles Tab

You can add CSS style rules for a post/page through this metabox field. Handy if you need to tweak a specific post or page display, without having all these post-specific rules clogging up your global stylesheet and thus loaded sitewide on every page. These rules are checked for singular pages and output in the <head> section of the page on display automatically. There is also an expand/collapse link for better access to viewing and editing this stylesheet rules textarea. There is also an added Quicksave CSS button for faster changes so you don't have to Update the post just for them to take effect.
[PerPost Styles post meta key: _bioship_perpoststyles (pre-2.1.0: _perpoststyles]

BioShip Value Filters

'.$filter." : ".$filters[$filter]['name'].'

'.$filters[$filter]['example'].'

'.$section['title'].'

BioShip Files and Hierarchy

BioShip uses an extended file hierarchy so you can easily override any of the Core Theme Files, Javascript and CSS Stylesheets by copying the existing files to your Child Theme and modifying them.

BioShip File Hierarchy

The file hierarchy will search for the file in this order and use the first matching file it finds:

1. the Child Theme subdirectories (if relevant)
2. the main Child Theme directory (ie. 'Stylesheet' directory)
3. the Parent Theme subdirectories (if relevant)
4. then main Parent Theme directory (ie. 'Template' directory)

CSS Stylesheets

Javascripts

Images

Core Theme File Hierarchy

The File Hierarchy also allows you to override Core Theme Files, though in most cases this would be unnecessary, as generally speaking you would leave these alone for Parent Theme updates and modify individual functions instead.

Core Theme Files

Default Template Files

Library Hierarchy

While the File Hierarchy also works for included libraries, if you want to use it for modifying a library, you will need to copy the entire library directory and subdirectories to your Child Theme to do so. This is because it will find the library loader file path and the library will load files relative to that.

BioShip Template Hierarchy

BioShip of course supports the default WordPress Template Hierarchy. So you can still implement these top level page templates overrides as you would in a standard theme (eg. page.php, home.php etc.)

Remember, due to the File Hierarchy, all template files parts are searched for in your Child Theme directory first. (This is ideally where you would be placing any customized templates anyway so they are all preserved in Parent Theme updates.) In all cases the Template Hierarchy will fall back to your Parent Theme (BioShip Framework) if there is no custom template found.

However, BioShip extends upon this default system in many different ways to make templating way more flexible. This of course could make it complex and unfamiliar as well - hence this guide is here to make it comprehensible!

First, by default, it uses a single index.php, loop-index.php and content/content.php to handle ALL page conditions. This keeps things super clean and means you can copy these default templates as starting points for custom ones. It also means if you prefer, there is no need at all use the template hierarchy - but it is available if needed. You can instead use the in-built combination of Value Filters and Layout Hooks for customizations. And since one of the most common thing a project needs is custom sidebars, for that see the Sidebar Guide.

Read on for deeper customizations, as you can override sublevel templates and parts at just about any level also... This is done by simply creating a template file with the proper naming convention to match the desired page condition. Again, none of these need to be used by default, but are made available for the most flexible template system possible.

BioShip Sidebar Guide

BioShip uses a uniquely flexible Sidebar template system to avoid using restrictive page layout templates. Sidebars output is pre-calculated in skull.php so that <body> classes and other tag classes can be set for the sidebar states.

Another difference you will find from other themes is that all possible sidebars are registered regardless of their setting display state. This is so the you can add widgets to them while inactive, which also allows you to use 'inactive' otherwise sidebars in filters or perpost overrides. Inactive sidebars are however lowercase and styled differently on the widgets page - and listed separate for ease of use.

Sidebar Template Override Usage

The main filter used to override this layout is skeleton_sidebar_layout_override. This allows you to conditionally use any sidebar in any of the possible positions for complete layout flexibility. Simply set one or two of the four template positions to a template name you wish to use (leaving the other two empty.) Note: when setting opposing sidebars, you can use either position 0 or 1 for left, and either position 2 or 3 for right.

Override Array Examples

Override Filter Example

';
	$html .= "add_filter('skeleton_sidebar_layout_override','my_portfolio_sidebars');".PHP_EOL;
	$html .= "function my_portfolio_sidebars(\$sidebars) {".PHP_EOL;
	$html .= "    if (get_post_type() == 'portfolio') {".PHP_EOL;
	$html .= "        // use portfolio.php for right sidebar and subportfolio.php for external right subsidebar".PHP_EOL;
	$html .= "        if (is_singular()) {\$sidebars = array('','','portfolio','subportfolio'};}".PHP_EOL;
	$html .= "        // use portfolio-archive.php for left sidebar and subportfolio-archive.php for right subsidebar".PHP_EOL;
	$html .= "        elseif (is_archive()) {\$sidebars = array('portfolio-archive','','','subportfolio-archive');}".PHP_EOL;
	$html .= "    }".PHP_EOL;
	$html .= "    // to preserve other sidebar behaviour, *always* return the first argument of the filter function".PHP_EOL;
	$html .= "    return \$sidebars;".PHP_EOL;
	$html .= "}".PHP_EOL."

PerPost Metabox Overrides

Sidebar templates can also be overridden on a post-by-post basis using the Theme Settings Metabox on the Writing Screen. Note that using these settings will override the filtered sidebar settings also, not just the default sidebar settings. Overrides are available for the sidebar templates, sidebar positions and sidebar widths. (Content width is available on this tab also.) For more information see the BioShip Theme Metabox section.

Template Hierarchy

Sidebar Template List

Sidebar Value Filters

Sidebar Width Filters

BioShip Grid System

';
	$html .= '<div class="container"><div class="eight columns">COLUMN A</div>
';
	$html .= '<div class="eight columns">COLUMN B</div></div>

';
	$html .= '<div class="container"><div class="eight columns"><div class="inner">COLUMN A</div></div>
';
	$html .= '<div class="eight columns"><div class="inner">COLUMN B</div></div></div>

add_action('{hook_name}', '{function_name}', {priority});

add_action('bioship_after_header', 'custom_after_header_function', 5);".PHP_EOL;
	$html .= "function custom_after_header_function() {echo 'Welcome!';}

add_action('bioship_after_header', 'custom_welcome_shortcode', 5);".PHP_EOL;
	$html .= "function custom_welcome_shortcode() {echo do_shortcode('[welcome_shortcode']);}

add_filter('bioship_header_widgets_position', 'custom_header_widgets_position');".PHP_EOL;
	$html .= "function custom_header_widgets_position() {return 2;}

add_filter('bioship_header_widgets_position', function(){return 2;} );

add_filter('bioship_header_widgets_position', function(){return -1;} );

bioship_remove_action('bioship_header', 'bioship_header_widgets');

add_action('init', 'custom_layout_femovals');".PHP_EOL;
	$html .= "function custom_layout_removals() {".PHP_EOL;
	$html .= "\t"."remove_action('bioship_header', 'bioship_header_widgets', 6);".PHP_EOL;
	$html .= "}

bioship_remove_action('bioship_header', 'bioship_header_widgets');".PHP_EOL;
	$html .= "add_action('bioship_navbar', 'bioship_header_widgets', 2);

add_filter('bioship_header_html_extra', 'custom_header_html_extras');
";
	$html .= "function custom_header_html_extras() {return '<div>Div Content</div>';}

THEMEPREFIX

THEMESLUG

THEMEKEY

THEMEDISPLAYNAME

THEMEHOMEURL

THEMESUPPORT

THEMESSL

THEMECHILD

THEMEPARENT

THEMEVERSION

THEMECHILDVERSION

THEMETITAN

THEMEOPT

THEMEHYBRID

THEMEDRIVE

THEMEKIRKI

THEMEDEBUG

THEMECOMMENTS

THEMETRACE

THEMEWINDOWS

<!-- #sidebar -->{Sidebar Output}<!-- /#sidebar -->

<!-- Debug Info Description: {INFO} -->

var_dump(debug_backtrace());