Learning Center

Plugins — Extending TypeRoom

Plug-ins can be used to run special functions within your TypeRoom Professional site. For a jump start, check out a tutorial showing you how to build a login script with password protected pages.

What is a Plugin?

In TypeRoom Professional, a plugin is simply a custom-built function that you can tie back into TypeRoom Professional. Plugins can be used to show dynamic content, for example, database driven content, or user-specific content.


Sample Plugins

We've created a few sample plugins to help you get started. These sample plugins will demonstrate the basics of plugins, including configuring parameters, returning data and using a custom icon.

To see our plugins, visit the plugin gallery.

Creating a Plugin

To get started, we recommend watching the screencast covering the basics of creating plugins:

Each plugin is created as an individual directory on the remote server, stored in the plugins folder with the published TypeRoom Professional folder. The directory name must match the name of the plugin. A plugin can contain the following files:

  • plugin.php - The plugin itself.
  • plugin_admin.php - An admin interface for the plugin.
  • plugin.png - A custom icon for the plugin. Must be a 100x100px png.
  • lib/ - A directory for storing additional files the plugin uses. Anything in the lib directory will be blocked from HTTP access for security purposes.

You must have publish the site to a remote server before plugins can be used, and TypeRoom Professional must be able to access your site in order for plugin detection to work properly. If you've added any access restriction, ensure you grant access to TypeRoom Professional's web server.

A plugin must be a written as a function which returns the content you would like to output. The function is named the same as the filename and prefixed with "typeroom_", for example, "typeroom_hello_world". Here's a sample plugin:

<?php
    
function typeroom_hello_world(&$page, $params = array()) {
    return "Hello world";
}

?>

Note that return is used here; this is important. Using echo or print will cause errors. Ensure all content you would like to output is returned at the end of the function.

The $page array gives you information about the current page. The following data is available:

  • id: This is the TypeRoom Professional id for the page. This will be unique to each page.
  • pageName: The name of the page. For example, if your page is at services/hosting/ the pageName would be hosting.
  • path: This is the path on the web server to the current page. Using the pageName example this would be services/hosting.

The $params array is simply an array of parameters you specify when calling the plugin in TypeRoom Professional.

Along with this data, you also have available a few constants:

  • PUBLIC_PATH: This is the path to your site after your domain, based on your Publish URL. For example, if your Publish URL is http://www.helloworld.com/mysite/, PUBLIC_PATH would return "/mysite/".
  • TR_PUBLISHED_VIEW: Returns true if you the plugin is being called from the published version of the site; returns false if the plugin is being called from the TypeRoom Professional version.

TypeRoom Professional plugins also allow you to pass information using HTTP GET parameters. This method is typically used to pass additional page specific data.


Plugin Parameters

If you'd like to allow content editors to easily insert parameter values, you can configure them through the plugin and an interface will be displayed when a plugin is inserted into a content area. To define a plugin parameter, use the following function:

tr_addparam($title(string),$metadeta(array));

The first value is the name of the parameter, the second is an array of metadata. The metadata array can contain the following information:

  • type: Can be either text or select.
  • data: When type is select this is the data for the drop list. It's an array of key => value pairs.
  • length: When type is text this is the maximum length of the string. Maximum size is 255 (varchar) and default size if not specified is 128.
  • title: Bold text that is the friendly name of the parameter.
  • description: Small text under the form element describing the plugin.

Here's an example:

tr_addparam(
	'video_id',
	array(
		'title'=>'Video ID',
		'description'=>'Enter the ID of the video you would like to embed'
	)
);

tr_addparam(
	'size',
	array(
		'title'=>'Size',
		'type'=>'select',
		'data'=>array(
			'small'=>'Small',
			'medium'=>'Medium',
			'large'=>'Large'
		)
	)
);

Additional Parameters

TypeRoom Professional plugins also have a few additional parameters you can set in the plugin to allow for special functionality. For instance, if your plugin has an administrator interface, you can link the Edit button in TypeRoom Professional directly to it.

List of additional parameters:

  • tr_admintitle(string): The display name of the plugin (shown in the list of plugins and the plugin admin window)
  • tr_adminwidth(int): The width of the admin window.
  • tr_adminheight(int): The height of the admin window.
  • tr_adminurl(string): Custom URL for the admin window. If not specified, TypeRoom will first look in for pluginname_admin.php in your plugin folder.
  • tr_hidecontrols(bool): Hides the edit controls when rendered in TypeRoom. Useful for plugins that return values to be used inside of tags (for example: <meta name="description" content="{{plugin name=description}}"/>). This should only be used for plugins included at the template level. If a plugin is included in a content area with the tr_hidecontrols option set to true, it will be converted to static content upon saving the content area.

Calling these special parameter functions outside of your plugin function declaration is perfect for default values. You can also call them within the function, in case you need dynamic values.

Example usage:

<?php
tr_admintitle("Photo Manager");
tr_adminwidth(500);
tr_adminheight(450);
tr_adminurl('http://testdomain.com/admin/tester.php');
function typeroom_tester($pagedata, $params = array()) {
	tr_adminurl('http://testdomain.com/admin/admin.php?instance='.$params['instance']);
	$output = "Page Data:\n".print_r($pagedata, true);
	$output .= "Params: \n".print_r($params, true);
	return $output;
}

Note: you can call these functions as many times as you want. The last one to be called will be the one that is used. To clear any of the parameters simply call the function passing no value.


Admin Interfaces

If your plugin has an administrative interface, you can link to it directly in the TypeRoom Professional interface via the Edit button. To do so, simple give the file the same name as the plugin and place it in the plugins/admin/ folder. You may also use a custom URL with the tr_adminurl() function.

To verify the request is coming through TypeRoom Professional, you can use our basic authentication, published to typeroom/system/tr_auth.php, by including it at the top of your plugin admin page.

Admin interfaces receive the same data as data normal plugins via the query string.


Plugin Icons

TypeRoom Professional allows you to easily customize the icon for your plugins. Simply upload a 100x100px PNG file to the plugins/icons/ folder, named the same as your plugin. For example, if your plugin is named map.php, the icon should be named map.png.


Manually Calling a Plugin

Manually calling a plugin in TypeRoom Professional is simple. You can call a plugin from within a content area or directly in a template using the Advanced Editor. Here's what the plugin call looks like:

{{plugin name="hello_world" param_one="test" param_two="test2"}}

Tutorial

Check out a tutorial that teaches how to build a simple login system with password protected pages in using TypeRoom Professional's plugin system.

Powered by Olark