The Secretary Docs

Tutorial 1: Two-Step Page with Varal Image Switcher

Demo / Source Files: index.php, styles.css, templates

Intro
Step 1
Step 2
Step 3
Step 4
Step 5
Step 6
Step 7

For this example we will be creating a design based on the portfolio of Laura Laine, a really fantastic fashion illustrator. Her website is a straightforward, two-column layout with a simple text listing of her works on the left and full-size images loading on the right. It will utilize two View Modes, List and Fullview. We will be using the Varal ImageSwitcher to create next, previous and numbered links so that users can easily cycle through images within each set. The ImageSwitcher is great because it takes care of generating those links for you, so all you have to do is edit the stylesheet to style those links.

First, we must write the HTML. Using your favourite text-editor or any HTML editing software, create a file named index.php. This will be the main page of your website. Copy and paste the following code:

<!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>
		<div id="WorkList">
			My Portfolio<br /><br />
			
		</div>
		<div id="Content">

		</div>
	</body>
</html>

What we have done here is define an area for our text links to reside (which will be referred to as work links from now on), called "WorkList", and another area for our images and any other content to load, simply named "Content". We have also written a simple title for the page which will appear before our work links.

The CSS (stylesheet) comes next. This will control the look and feel of your page, as well as define how the elements are placed on the page. Create a new file called styles.css and paste in the following:

html {
	font-size: 62.5%;
	padding: 0;
	margin: 0;
}

body {
	padding: 20px;
	margin: 0;
	font-family: Georgia, serif;
	font-size: 1.2em;
	color: #000;
	background: #FFF;
}

#WorkList {
	float: left;
	margin-right: 20px;
	width: 300px;
	background: #FFF;
}

#Content {
	float: left;
}

#WorkList a, #WorkList, #Content {
	font-size: 0.9em;
	text-transform: uppercase;
	color: #000;
}

Now, we must attach our stylesheet to our page. In the <head> section of your HTML code, enter the following line:

<link rel="stylesheet" href="styles.css" type="text/css" media="screen" />

Your HTML code should now look like this:

<!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>
		<link rel="stylesheet" href="styles.css" type="text/css" media="screen" />
	</head>
	<body>
		<div id="WorkList">
			My Portfolio<br /><br />
			
		</div>
		<div id="Content">
		
		</div>
	</body>
</html>

All of this can of course be customized. If you are using an editor such as Dreamweaver you can preview your site and make changes to colours, fonts, sizes and add graphics if you wish.

The next step is to create a template that will be used to display our text links. Log-in to your installation of the secretary and navigate to Gallery > Templates > Add. You can enter any name for this template, but for the sake of this tutorial we will call our new template "Varal". Click the "List" tab and enter the following:

<?php title_linkToFullview(); ?><br />

Save the template (click "Create Template"). Ready to go! Now, here comes the fun part: getting the secretary into your page and loading in your newly dynamic content! Switch back to your code and at the the very top, before any HTML, insert the following:

<?php
	$HQ= "/path/to/secretary";
	include_once "$HQ/secretary_loader.php";
	
	secretary_load( "gallery" );
?>

The $HQ variable simply identifies where your installation of the secretary is on your server, so that required files, and of course, your content can be accessed. This should be the absolute path to the folder where you installed the secretary, and usually looks something like this: /home/public_html/username/domain.com/secretary. If you are unsure of your absolute path, go to the Home > About section of the system where you will find information about your installation including the absolute path.

Next, find the line <div id="WorkList">. After your site title, paste the following:

<?php
$settings= "template= Varal";
bam( "gallery", $settings );
?>

This next step utilizes View Modes. We do this because we want to have some default content in the content area, but want it hidden when our users are viewing a set. This is very simple to do - no sweat! Insert this next code snippet after the line <div id="Content">:

<?php
	if ( gallery_mode_is_fullview() ):
		gallery_varal_imageswitcher( get_selected_set() );
	else:
?>
Welcome!
<?php
	endif;
?>

We use the gallery_mode_is_fullview() function to determine whether the user has clicked on a work link - if so, then we need to display the content the user has requested. The gallery_varal_imageswitcher() function takes care of all the messy stuff for you, so you do not need to write anything more. By using the get_selected_set() function, we tell the image switcher to show the images for the set selected by the user (the set they clicked on). Look down a few lines and you will see some text saying "Welcome!". This is the default content that will be loaded when no work link has been clicked. You can fill this area with anything you wish, or even leave it blank.

The final step is to style our ImageSwitcher. Add the following to your styles.css file.

.imgsw_image {
	border: 0;
}

.imgsw_list_numbers a, .imgsw_prevnext a {
	color: #000;
	margin-right: 10px;
}

.imgsw_list_numbers a.active {
	font-weight: bold;
}

.imgsw_prevnext, .imgsw_list_numbers {
	display: inline;
}

.imgsw_viewport {
	margin-top: 10px;
}

Save your page, upload it to your server and that is it! Assuming you have created at least one set, you should see a listing of them on the left. It is important to note that there are many more options to control how the ImageSwitcher looks and behaves (which are out out of the scope of this tutorial), so it is recommended that you read the documentation.

Tutorial 2: Single Page Portfolio with Anchor Links

Demo Page / Source Files: index.php, styles.css, templates

Intro
Step 1
Step 2
Step 3
Step 4
Step 5
Step 6

In this example we will create a single page portfolio with anchor links at the top. When clicked, these anchor links will make the user's browser jump down to that specific work, wherever it lies on the page. Take a look at the demo page to get a clear idea.

The first step is to write our HTML. Using your favourite text-editor or any HTML editing software, create a file named index.php. This will be the main page of your website. Copy and paste the following code:

<!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>
		<div class="center">
			<span class="title">My Portfolio</span><br />
			<span class="sub_title">A collection of random works.</span>
			<div id="WorkLinks">

			</div>
			<div id="WorkList">

			</div>
		</div>
	</body>
</html>

As with the first example, this is very simple mark-up. We have created an area for our anchor links and another area for our listing of works. There is also a a title and sub-title, and the whole layout is wrapped in a container so that we can center our content on the page.

The next step is to create our CSS. Create a new file called styles.css and paste in the following:

html {
	font-size: 62.5%;
	padding: 0;
	margin: 0;
}

body {
	padding: 0;
	margin: 0;
	font-family: Georgia, serif;
	font-size: 1.2em;
	color: #555;
	background: #222;
}

.center {
	width: 75%;
	margin-left: auto;
	margin-right: auto;
	background: #FFF;
	padding: 15px;
}

.title {
	font-size: 1.7em;
	font-style: italic;
	font-weight: bold;
}

.sub_title {
	font-size: 0.9em;
	font-style: italic;
}

#WorkLinks {
	padding: 5px;
	margin: 10px 0 20px 0;
	color: #777;
	background: #EEE;
}

Now, we must attach our stylesheet to our page. In the <head> section of your HTML code, enter the following line:

<link rel="stylesheet" href="styles.css" type="text/css" media="screen" />

So that your HTML code now looks like this:

<!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>
		<link rel="stylesheet" href="styles.css" type="text/css" media="screen" />
	</head>
	<body>
		<div class="center">
			<span class="title">My Portfolio</span><br />
			<span class="sub_title">A collection of random works.</span>
			<div id="WorkLinks">

			</div>
			<div id="WorkList">

			</div>
		</div>
	</body>
</html>

If you take a look at your page now, it will look very uninteresting, so let's get the secretary in there. In order to do so, we must make a custom template. For this specific page design we will be requiring two templates: one for the anchor links and one to control how our works will be listed on the page. Log-in to your installation of the secretary and navigate to Gallery > Templates > Add. Name this template "Single Page Listing". Click the "List" tab (we want to edit the List view template), enter this code and save the template:

<a href="#<?php set_simpletitle(); ?>"><?php set_title(); ?></a>

OK, we have a couple things going on here. Because we want to create a link for each set, we begin by writing the HTML code for a link (<a href="link_location">Text to Show</a>). Next, we want to make the link take our viewers to a specific point on the page, so we will link to what is called an "anchor". These anchors will be taken care of just below. To do this, we change the href attribute to "#<?php set_simpletitle()(); ?>", which is a Gallery function that outputs the set's "simple title" (a version of the title that does not contain spaces or punctuation, in lowercase). You could substitute this with any function, such as set_title() or set_id(), for example. The # sign tells the browser that the target of the link is on the current page, so don't remove it!

And the last little bit is using the set_title() function to display the set's title (no, really?!) as the text to be clicked on. Again, any of the view functions can be used here.

And now for our second template. Name this one "Single Page Works", enter the following and then save the template:

<div class="work_block">
	<a name="<?php set_simpletitle(); ?>"></a>
	<div class="images">
		<?php set_list_images(); ?>
	</div>
	<div class="info">
		<strong><?php set_date("M d Y"); ?></strong> / <?php set_description();?>
	</div>
</div>

Here is where we make a little bit of magic to make our anchor links work. Ignoring the rest of it, focus on the line "<a name="<?php set_simpletitle(); ?>"></a>". Here we use the HTML for a link again, but instead of a "href" attribute we use only the "name" attribute. To make it all work, we use the same view function as we did for the "href" attribute above (so if you have used a different one in your links, make it match here). This makes the two "reference" each other, if you will.

We use the set_list_images() function to display our images. This will simply display each image in the set, one next to the other (so if you have super large images this example may look a little screwy for you). The rest of this template is simply presentational HTML, making use of two other view functions to display the date and set description.

Now let's get our content into our page. Switch back to your HTML code and add an $HQ link and load function to the very top (make sure to set the path properly!):

<?php
	$HQ= "/path/to/secretary";
	include_once "$HQ/secretary_loader.php";
	
	secretary_load( "gallery" );
?>

Find the line <div id="WorkLinks"> and after it write a bam() function with the template option set appropriately, like so:

<?php
	$settings= "template= Single Page Listing";
	bam( "gallery", $settings );
?>

Next, find the line <div id="WorkList"> and make another bam() function with the template value changed to "Single Page Works". Take a look at the source file if you are confused.

Try uploading everything to your server now and checking it out in your browser. You should see some text links at the top, and a listing of your images below. But it is quite ugly, isn't it? Let's make a quick detour to our CSS file and add this next bit to it:

#WorkLinks a {
	margin: 0 5px 0 5px;
	color: #477DF4;
}

#WorkLinks a:hover {
	color: #8B32B8;
}

.work_block {
	margin-bottom: 20px;
	border-bottom: 1px solid #CCC;
}

.work_block .info {
	padding: 5px;
	background: #EEE;
}

.images img {
	margin-right: 1px;
}

And now that we are in a styling mode, let's return to our templates. Navigate to Gallery > Templates > Edit and select your "Single Page Listing" template. Append this to the code:

<?php	
	if ( if_this_set_is_not_last() ):
?>
 / 
<?php
	endif;
?>

I want my links to be separated by a slash, but you can have them separated by anything you want (even images! - just enter an HTML "img" tag). The problem is that if we simply add a slash after the link, the last link displayed in our list will have a slash after it as well. As a picky designer, I do not like this - it simply does not terminate nicely. To save my design, I will make use of another really nifty view function, if_this_set_is_not_last(), which, as the name suggests, determines if the link is NOT the last one to be displayed. If it is not, then the slash should be included. There is no opposite case for this (meaning, if the link is last), so here is how it should look if you want your list to end with something:

<?php	
	if ( if_this_set_is_not_last() ):
?>
 / 
<?php
	else:
?>
 INSERT ANYTHING HERE
<?php
	endif;
?>

Save the template, upload the files and point your browser to your new one page portfolio with anchor links. Easy, huh?

Sets

View Modes

Library

Integrating The Secretary

Tutorial 1: Two-Step Page with Varal Image Switcher

Tutorial 2: Single Page Portfolio with Anchor Links