Blog

HomeBlogTop Quark Architecture – Filters, Actions & Shortcodes

Top Quark Architecture – Filters, Actions & Shortcodes

As part of the ongoing documentation effort here at TopQuark.com, here is a summary of all of the available Filters, Actions and Shortcodes within the Top Quark Architecture plugin – available at wordpress.org/extend/plugins/topquark

 

All Filters

All Actions

All Shortcodes

Filters

 

Back to Index

set_{ContainerName}_columns

This is a dynamic filter for all ObjectContainers
Examples: set_GalleryContainer_columns, set_ArtistContainer_columns
Called From: topquark/lib/packages/Common/DB_Object.php (DB_Object constructor method)
Arguments: (array) $column_names

This filter is used to dynamically add columns to a Top Quark ObjectContainer. This is one of a few filters to call if you want to add custom fields to a container. For a complete example on adding custom fields, see the blog post at topquark.com/blog/2011/07/08/adding-new-fields-to-a-top-quark-object/

Usage
add_filter('set_SelfHostedPluginContainer_columns','my_mods_set_PluginContainer_columns');
function my_mods_set_PluginContainer_columns($colname){
    $colname['SelfHostedPluginPrice'] = 'SelfHostedPluginPrice';
    return $colname;
}

 

Back to Index

extend_{ContainerName}

This is a dynamic filter for all ObjectContainers
Examples: extend_GalleryContainer, extend_ArtistContainer
Called From: topquark/lib/packages/Common/ObjectContainer.php (constructor) and topquark/lib/packages/Common/FancyObjectContainer.php (constructor)
Arguments: (array) First item is a reference to ObjectContainer instance

This filter allows you to set custom parameters and variables on any ObjectContainer instance. It’s useful if you need to make global changes to the ObjectContainer class that will apply to every instance

Usage
add_filter('extend_ArtistContainer','my_mods_extend_ArtistContainer');
function my_mods_extend_ArtistContainer($args){
	$ArtistContainer = & $args[0];

	// Use a different table name for this object
	$ArtistContainer->setTableName('my_artist_table_name');
	$ArtistContainer->ensureTableExists();
    return null; // no need to return anything - everything is adjusted via reference
}

 

Back to Index

extend_{ObjectClass}

This is a dynamic filter for all Parameterized_Objects
Examples: extend_Gallery, extend_Artist
Called From: topquark/lib/packages/Common/Parameterized_Object.php (constructor)
Arguments: (array) First item is a reference to Parameterized_Object instance

This filter allows you to modify any Parameterized_Object (the superclass for Top Quark Objects that talk to ObjectContainers).

Usage
add_filter('extend_Artist','my_mods_extend_Artist');
function my_mods_extend_ArtistContainer($args){
	$Artist = & $args[0];

	$Artist->setParameter('MyCustomParm','FeeFieFoFum');

    return null; // no need to return anything - everything is adjusted via reference
}

 

Back to Index

add_{ObjectType}_object

update_{ObjectType}_object

These are dynamic filters for all ObjectContainers
Examples: add_Gallery_object, add_Artist_object, update_Gallery_object, update_Artist_object
Called From: topquark/lib/packages/Common/ObjectContainer.php (addObject / updateObject method) and topquark/lib/packages/Common/FancyObjectContainer.php (addObject / updateObject method)
Arguments: (Parameterized_Object) $object

These filters allow you to massage an object before it is added to the object container or before it is updated. The adding/update methods within the ObjectContainer are the methods that actually manipulate the MySQL database to store the object. This is one of a few filters to call if you want to add custom fields to a container. For a complete example on adding custom fields, see the blog post at topquark.com/blog/2011/07/08/adding-new-fields-to-a-top-quark-object/

Usage
add_filter('update_SelfHostedPlugin_object','topquark_mods_update_SelfHostedPlugin_object');
add_filter('add_SelfHostedPlugin_object','topquark_mods_update_SelfHostedPlugin_object');
function topquark_mods_update_SelfHostedPlugin_object($object){
    if (isset($_POST) and $_POST['form_submitted'] != ""){
        $object->setParameter('SelfHostedPluginPrice',$_POST['SelfHostedPluginPrice']);
    }
    return $object;
}

 

Back to Index

get_all_{ObjectType}_where_clause

get_all_{ObjectType}_sort_field

get_all_{ObjectType}_sort_dir

These are dynamic filters for all ObjectContainers
Examples: get_all_Gallery_where_clause, get_all_Gallery_sort_field
Called From: topquark/lib/packages/Common/ObjectContainer.php (getAllObjects method)
Arguments: (mixed) $mixed

These filters allow you to override the default behaviour of the getAllObjects method of any ObjectContainer. Useful if you want objects to be retrieved in a specific order or according to a specific WHERE condition.

Usage
// These functions change the default behaviour of the GalleryContainer::getAllGalleries() method
add_filter('get_all_Gallery_where_clause','topquark_mods_Gallery_where_clause');
function topquark_mods_Gallery_where_clause($whereClause){
	// Get all public and private galleries (as opposed to the default just public)
	$wc = new whereClause();
	$wc->setConnector('OR');
	$wc->addCondition('GalleryStatus = ?','public');
	$wc->addCondition('GalleryStatus = ?','private');
	return $wc;
}

add_filter('get_all_Gallery_sort_field','topquark_mods_Gallery_sort_field');
function topquark_mods_Gallery_sort_field($sort_field){
	// Sort by Gallery Name, as opposed to the default sort index
	$sort_field = array('GalleryName');
	return $sort_field;
}

add_filter('get_all_Gallery_sort_dir','topquark_mods_Gallery_sort_dir');
function topquark_mods_Gallery_sort_dir($sort_dir){
	// Sort by Gallery Name, Ascending
	// Make sure the count in this array matches the count in the $sort_field array
	return array('ASC');
}

 

Back to Index

set_user_conf_file_{PackageName}

This is a dynamic filter for all Top Quark Packages
Examples: set_user_conf_file_Gallery, set_user_conf_file_FestivalApp
Called From: topquark/lib/packages/Common/Package.php (loadUserConf method)
Arguments: (string) $path_to_conf_file

These filters allow you to override the default parameters of a Top Quark package. The configuration file conf.user.php is a relic of the days before Top Quark Architecture became a WordPress plugin. See the file topquark/lib/packages/Gallery/conf.user.php as an example of how to format it. This filter allows you to specify your own configuration file for any Top Quark package

Usage
add_filter('set_user_conf_file_Gallery','topquark_mods_set_user_conf_file_Gallery');
function topquark_mods_set_user_conf_file_Gallery($userConf){
	// Set a configuration file in this mods plugin
	return ABSPATH.'/wp-content/topquark-mods/Gallery/conf.user.php';
}

 

Back to Index

addition_conf_{PackageName}

This is a dynamic filter for all Top Quark Packages
Examples: addition_conf_Gallery, addition_conf_FestivalApp
Called From: topquark/lib/packages/Common/Package.php (loadUserConf method)
Arguments: (array) Reference to Package object

These filters allow you to specify additional configuration options for the Package. It passes the Package object by reference and ignores what is returned.

Usage
add_filter('addition_conf_Gallery','topquark_mods_addition_conf_Gallery');
function topquark_mods_addition_conf_Gallery($args){
	$Package = & $args[0];
	$Package->my_config_option = '3.14159';
	return null;
}

 

Back to Index

set_user_functions_file_{PackageName}

This is a dynamic filter for all Top Quark Packages
Examples: set_user_functions_file_Gallery, set_user_functions_file_FestivalApp
Called From: topquark/lib/packages/Common/Package.php (loadUserFunction method)
Arguments: (string) $path_to_conf_file

These filters allow you to override the default user functions of a Top Quark package. The file user.functions.php is where all of the Paint & Retrieve methods for the Package are defined. It would be a rare case that you would need to override it completely. Maybe you find that the existing user.functions.php file doesn’t give you the hooks that you need. In that case, copy and modify as you wish and use this filter to point the package to your modified file.

Usage
add_filter('set_user_functions_file_Gallery','topquark_mods_set_user_functions_file_Gallery');
function topquark_mods_set_user_functions_file_Gallery($userFunctions){
	// Set a configuration file in this mods plugin
	return ABSPATH.'/wp-content/topquark-mods/Gallery/user.functions.php';
}

 

Back to Index

{PackageName}_paint

{PackageName}_retrieve

{PackageName}_ajax

These are a dynamic filters for all Top Quark Packages
Examples: Gallery_paint, FestivalApp_ajax
Called From: topquark/lib/packages/Common/Package.php (Paint / Retrieve / Ajax methods)
Arguments: (mixed) $mixed, (array) $parms, (array) Reference to Smarty object

These filters allow you to override the default Paint, Retrieve or Ajax behaviour of Top Quark packages. Returning anything but `false` will override the default behaviour. This can be useful for adding in custom parameters within the Top Quark Shortcodes.

Usage
add_filter('Gallery_paint','topquark_mods_Gallery_paint',10,3);
function topquark_mods_Gallery_paint($markup = false,$parms,$smarty_array){
	$Smarty = & $smarty_array[0];

	if ($parms['my_custom_attribute'] == 'do_it'){
		$markup = 'Hello World'; // do your custom painting here
		$markup.= '......';
	}
	return $markup;
}

 

Back to Index

topquark_gallery_base_url


Called From: topquark/lib/packages/Gallery/conf.user.php
Arguments: (string) $url

This filter allows you to override the default URL where the Top Quark Gallery gets rendered. By default, it is simply the current permalink. If you want to make it a specific page on your site, then you can use this filter

Usage
add_filter('topquark_gallery_base_url','topquark_mods_gallery_base_url');
function topquark_mods_gallery_base_url($url){
	// Note, you need there to be at least one url param (i.e. ?show=photos).
	// It can be a dummy parm, but the architecture currently expects the URL to
	// have a question mark in it.  It's a little dumb, I know.  I'll fix it down the road,
	// but for now, that's the sitch.
	$url = get_bloginfo('url').'/photos/?show=photos';
	return $url;
}

 

Back to Index

set_gallery_dimension_callbacks


Called From: various
Arguments: (array) $callbacks, (string) $gallery_name

This filter allows you to specify the dimensions of the thumb, resized and original images checked into the Top Quark Gallery. The default thumbnail size is 133×100 (exact). The default resized image is 400×400 (keeping aspect ratio, constrained to box). The default size for the original image is 1500×1500 (keeping aspect ratio, constrained to box). The example below creates a larger thumbnail and tells the ImageLibrarian to keep the Original image around (as opposed to resizing to 1500×1500)

Usage
	add_filter('set_gallery_dimension_callbacks','conf_plugin_set_gallery_dimensions_callback',5,2);
	function conf_plugin_set_gallery_dimensions_callback($callbacks,$gallery_name){
		if ($gallery_name == 'General Artist Images'){
	        $DimensionCallbacks = array();
	        // get an exact fit to 160x160 for the artists & keep the original
	        $DimensionCallbacks['Thumb'] = create_function('','return array("width" => 160, "height" => 160, "conditions" => '.RESIZE_CROP.');');
	        $DimensionCallbacks['Original'] = create_function('','return array("width" => 0, "height" => 0, "conditions" => '.RESIZE_CONDITIONS_DEFAULT.');');
			$callbacks = $DimensionCallbacks;
		}
		return $callbacks;
	}

 

Back to Index

Smarty_Instance_resource_name


Called From: topquark/lib/Smarty_Instance.class.php (fetch method)
Arguments: (string) $resource_name, (array) Reference to Smarty object

This is a very useful filter that is used to override the smarty template any time the $smarty->fetch($template) method is called. It gives you complete control over the view and allows you to construct it any way you want. Simply filter on the $resource_name and return your own template if you wish.

Note: There are some template caching functions that can sometimes play havoc with this feature. If you are having trouble getting your template to render properly, try deleting all compiled files in the directory wp-content/assets/smarty/templates_c

Usage
add_filter('Smarty_Instance_resource_name','topquark_mods_Smarty_Instance_resource_name',10,2);
function topquark_mods_Smarty_Instance_resource_name($resource_name,$args){
	$smarty = & $args[0]; // a reference to the smarty object
	switch($resource_name){
	case 'gallery.thumbnails.tpl':
		// Load my own
		$smarty->template_dir = dirname(__FILE__).'/smarty/'; // a subdirectory of the current plugin
		// Note: the template_dir gets restored fully when this call to $smarty->fetch() is finished
		// Now, a file called gallery.thumbnails.tpl in the ./smarty subdirectory gets rendered.
		break;
	}
	return $resource_name;
}

 

Back to Index

Smarty_Instance_smarty_include


Called From: topquark/lib/Smarty_Instance.class.php (_smarty_include method)
Arguments: (array) $params, (array) Reference to Smarty object

This is like the Smarty_Instance_resource_name filter except it kicks in when a template is {include}’d in another template, as opposed to ->fetch()’d. $params are the parameters included in the {include} statement.

Usage
	add_filter('Smarty_Instance_smarty_include','mods_smarty_include',10,2);
	function mods_smarty_include($params,$args){
		$smarty = $args[0];
		extract($params);
		switch ($smarty_include_tpl_file){
		case 'ifestivalapp.artist.tpl':
			$smarty->template_dir = dirname(__FILE__).'/smarty/';
			break;
		}
		return $params;
	}

 

Back to Index

tqp_do_get_header

tqp_do_get_footer


Called From: topquark/lib/Standard.php (tqp_get_header / tqp_get_footer methods)
Arguments: (bool) $do_it

For Top Quark Packages that live outside of the WordPress rendering engine (poMMo for WordPress, for example), Top Quark Architecture tries to render the content in a WordPress-like way by calling the appropriate WordPress head and foot functions. If you want to override this behaviour and handle things yourself, return false to these filters and then add your own actions with add_action(‘tqp_get_header’) and add_action(‘tqp_get_footer’).

Usage
	add_filter('tqp_do_get_header',create_function('$a','return false;'));
	add_filter('tqp_do_get_footer',create_function('$a','return false;'));

 

Back to Index

tqp_extra_header_markup

tqp_extra_footer_markup


Called From: topquark/lib/Standard.php (tqp_get_header / tqp_get_footer methods)
Arguments: (string) $markup

Allows you to add extra markup to the Top Quark quasi-WordPress header and footer. For Header, it gets added to the end of the Top Quark header markup. For Footer, it gets added to the beginning.

Usage
	add_filter('tqp_extra_header_markup','mods_tqp_extra_header_markup');
	function mods_tqp_extra_header_markup($markup){
		return 'Here is some extra markup';
	}

 

Back to Index

{PackageName}_{AdminPageParm}_{TabID}_items

This is a dynamic filter for all Top Quark admin pages
Examples: SelfHostedPlugins_edit_SelfHostedPlugin_items, Gallery_edit_Gallery_items
Called From: topquark/lib/TabbedForm.php (displayTabs method)
Arguments: (array) $items,(string) $TabID

This is another important filter for when you want to add custom fields to a Top Quark Object. It is the filter that will render out the input fields on the admin page for working with objects within that package. For an example of using this filter, please see the blog post at topquark.com/blog/2011/07/08/adding-new-fields-to-a-top-quark-object/

The filter name can be a little confusing, but if you look at the source code for any Top Quark admin pages, you’ll find a comment of the form `<!– filter: SelfHostedPlugins_edit_SelfHostedPlugin_items –>` that will inform you of the filter name to call.

Usage
add_filter('SelfHostedPlugins_edit_SelfHostedPlugin_items','topquark_mods_SelfHostedPlugin_items');
function topquark_mods_SelfHostedPlugin_items($items){
    $id = $_REQUEST['shpid']; // Make sure this is the ID used within the actual edit page
    $Container = new SelfHostedPluginContainer();
    if ($id == "" and $_POST['form_submitted'] == 'true'){
        global $topquark_last_id;  // This gets set in this function
        $id = $topquark_last_id;
    }
    if ($id != ""){
        // They've just added the row, let's get it.
        $Plugin = $Container->getSelfHostedPlugin($id);
    }
    else{
        $Plugin = new SelfHostedPlugin();
    }
    $items[] = HTML_Form::returnTextRow('SelfHostedPluginPrice','Plugin Price:',$Plugin->getParameter('SelfHostedPluginPrice'));
    return $items;
}

Actions

 

Back to Index

new_{ObjectClass}_object_id

This is a dynamic filter for all Top Quark ObjectContainers
Examples: new_SelfHostedPlugin_object_id, new_Gallery_object_id
Called From: topquark/lib/packages/Common/ObjectContainer.php (addObject method) and topquark/lib/packages/Common/FancyObjectContainer.php (addObject method)
Arguments: (string) $object_id

This filter allows a way to store the object ID for the object just added to the container. This is an important feature to use when adding custom fields to an ObjectContainer. For an example of using this filter, please see the blog post at topquark.com/blog/2011/07/08/adding-new-fields-to-a-top-quark-object/

Usage
/*******************************************************
* This function will store the last ID added.  Useful
* in the above functions when adding an object.
********************************************************/
add_action('new_SelfHostedPlugin_object_id','topquark_mods_new_object_id');
global $topquark_last_id;
function topquark_mods_new_object_id($id){
    global $topquark_last_id;
    $topquark_last_id = $id;
}

 

Back to Index

tqp_get_header

tqp_get_footer


Called From: topquark/lib/Standard.php
Arguments: none

For Top Quark Packages that live outside of the WordPress rendering engine (poMMo for WordPress, for example), Top Quark Architecture tries to render the content in a WordPress-like way by calling the appropriate WordPress head and foot functions. You can add to these headers and footers by using these actions.

Usage
	add_action('tqp_get_header','mods_tqp_get_header');
	function mods_tqp_get_header(){
		echo "This will get echoed when the Top Quark header gets constructed";
	}

 

Back to Index

{PackageName}_{AdminPageParm}_display_tabs


This is a dynamic action that gets called for any Top Quark admin page that displays a TabbedForm
Called From: topquark/lib/TabbedForm.php (display method)
Arguments: (string) $action, (array) reference to TabbedForm object

This action is useful when wanting to customize any Top Quark Admin page. Most Top Quark Admin pages are displayed using a TabbedForm object. This action gets performed before display and gives you a chance to manipulate the TabbedForm object. The action name can be a little confusing, so a comment of the form `<!– action: SelfHostedPlugins_edit_display_tabs –>` gets rendered out. Just look at the source code of the admin page you’re interested in to find the name of the action to call.

Usage
	add_action('SelfHostedPlugins_edit_display_tabs','mods_SelfHostedPlugins_edit_display_tabs',10,2);
	function mods_SelfHostedPlugins_edit_display_tabs($action,$args){
		$TabbedForm = & $args[0];
		echo "This will get displayed above any tabbed forms in the Top Quark admin area";
	}

Shortcodes

 

Back to Index

[topquark]


Examples: [topquark action=paint package=Gallery subject=Images]
Common Arguments: action=paint, package={$PackageName}, subject={Subject}

This is the main shortcode offered by the Top Quark Architecture. Before it became a WordPress plugin, the Top Quark Architecture had it’s own quasi-shortcoding nomenclature. This shortcode is a direct translation of that. Basically, when calling this shortcode within WordPress, you need to pass it minimally a PackageName and an action (which will almost always be `paint`). It tells the architecture to call the Paint method within the user.functions.php file of the specified package. The third most common attribute you would pass it would be the `subject`, which tells the user.functions.php method what to actually paint.

If all you’re doing is using Top Quark Architecture as a gallery plugin, you’ll want to know about these two versions of the shortcode:

`[topquark action=paint package=Gallery subject=Breadcrumbs]` – paints the breadcrumbs for viewing the gallery (including a link display the slideshow)
`[topquark action=paint package=Gallery subject=Images]` – paints the thumbnails of your Gallery. If you specify an attribute for `gid`, then it paints the thumbs for that particular gallery, otherwise, it paints a landing page showing all of the galleries. The shortcode automatically handles the drill-down into the gallery.

Usage
	<!-- paints the gallery sandwiched top and bottom by the breadcrumbs -->
	[topquark action=paint package=Gallery subject=Breadcrumbs]
	[topquark action=paint package=Gallery subject=Images]
	[topquark action=paint package=Gallery subject=Breadcrumbs]

 

Back to Index

[capture]


Examples: [capture var=foo]This gets assigned to foo[/capture]

This is a shortcode that allows you to store values accessible in your plugins by specifying them in the body of your post or page. For example, if you call `[capture var=blah]This is a Test[/capture]` and then afterwards call `[my_shortcode]`, within the body of your my_shortcode function, you can call `get_captured(‘blah’)` to retrieve “This is a Test”.

Usage
<!-- within your page or post -->
[capture var=foo]This gets assigned to foo[/capture]

	add_shortcode('my_shortcode','my_shortcode');
	function my_shortcode($atts,$content="",$code=null){
		return get_captured('foo'); // returns "This gets assigned to foo"
	}
12
SEP
0


Related Posts

Categories: Blog, Documentation, How-To

Tags:

About the Author

Top Quark is Trevor Mills is Top Quark. He is they as you are me and we are all together. He holds an Engineering degree, specializing in high energy physics, he plays bass in the Juno award winning band Digging Roots and he lovely loves his family. Top Quark’s suite of WordPress plugins are just what you’re looking for.
Subscribe to Comments

Add a Comment