Tutorials » Getting Started

The $HQ link

The $HQ Link is the single most important aspect of setting up your page to work with the secretary. Without, nothing works! What it does is sets up a connection with the system itself, so that all your content and data can be displayed on your page. Sounds like a big job but the process has been made super simple for you. Take a look: 

<?php
	$HQ= "/your/absolute/path";
	include_once "$HQ/secretary_loader.php";
?>

Simply change the $HQ value (the text between the quotes) to your absolute path and include the snippet in your code. An absolute path usually looks like this: /home/user/domain/folder. If you are unsure of your absolute path either contact your host or point your browser to your installation of the secretary and navigate to Home > About. There you will find information about your installation including the absolute path.

It is recommended that the $HQ Link be included at the top of your page's code, so that the connection is made instantly and more so, for organization sake.

The secretary_load() Function
secretary_load( $module );

In order to include content from a certain module in the secretary, you must load that specific module into your page. This is done simply by making a call to the secretary_load() function with the name of the module you want to load. You must write a load call for every module you wish to include. It is recommended that your load calls be made at the top of the page along with the $HQ Link. Here is an example of how it would look with the $HQ Link (this example loads the Gallery module): 

<?php
	$HQ= "/your/absolute/path";
	include_once "$HQ/secretary_loader.php";
	
	secretary_load( "gallery" );
?>
Simple!

The bam() Function
bam( $module, [$settings] );

The bam() function is the second most important part of getting your page to interact with the secretary. As with the $HQ Link, without it, nothing happens! However, it is not absolutely necessary. Omitting it simply will remove content created with the secretary from your page. This function is what actually places your content on the page. There is no limit to how many times it can be called on a single page, meaning you can display several different categories and templates (ie. different bits of content) from any given module.

The function takes two parameters. The first is the module name (in lowercase). The second is an array of settings to control things like which template to use, which category (or categories) to display, and various other options a module may have. The settings parameter is optional, meaning that if it is omitted, then the module defaults will be used instead. Here is an example of how to use the function with the Gallery module: 

<?php	
	$settings= "template= CoolTemplate, category= list, of, categories";
	bam( "gallery", $settings );
?>

Setting Up Your Page

So, you have your page perfectly designed to the very pixel and all that is needed is your content. This short example demonstrates the usage of the $HQ Link, secretary_load() and bam() functions, as it would look with HTML code: 

<?php
	// The all important HQ Link
	$HQ= "/your/absolute/path";
	include_once "$HQ/secretary_loader.php";
	
	// Load in the Gallery module
	secretary_load( "gallery" );
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
	<head>
		<title>My Portfolio</title>
	</head>
	<body>
		Some text.
		<!-- Here is where my content should load -->
		<?php
			$settings= "template= CoolTemplate, category= Personal Projects";
			bam( "gallery", $settings );
		?>
	</body>
</html>

Simply place your bam() function wherever you want your content to be displayed, without affecting your page design. Yay! Take a look at the tutorials for more detailed/complex uses.