This article shows you how to implement header image selection via the media manager in your serendipity templates configuration.
I first introduced this feature in the beautiful day theme and it proved to be quite popular.
There are two parts to this guide. In part one I explain how it all works. In part two I explain what you have to do to use it in your templates.
Part 1 : How it all works
$template_config content type
The $template_config array is used to create a form based user interface for theme configuration in the serendipity administration suite "manage styles" section. There is some documentation on the serendipity site that takes the new developer through the use of this array.
One type of $template_config option is the content type. Its not covered by the docs on the s9y site at the time of writing but believe me it exists! The content type allows you to emit HTML:
<?php
$template_config=
array("var"=>
"my_html",
"type"=>"content",
"default"=>"<em>Hello</em> <strong>world</strong>!"
);
?>
This will display "Hello world!" in the admin theme configurator.
So now we know how to emit HTML and javascript as well. That means we can include our own form elements and have them show up in the admin theme config. Lets now consider the next hurdle.
Saving form data
When using the content type option in the $template_config array to emit a custom form you are faced with the problem of how to save the data entered in the form. First lets take a look at the HTML source code of serendipity generated forms:
<input class="direction_ltr" type="text" name="serendipity[template][navlinklabel6]" value="" size="30" />
<input class="direction_ltr" type="text" name="serendipity[template][navlinkurl6]" value="" size="30" />
Notice the names of the form elements. They always have the same prefix "serendipity[template]". The last part is the variable that you set in the $template_config array (var key). So does that mean if you emit HTML that mimics this, serendipity will automatically save it in the database? Yes! For example if you create an input box in this fashion:
<?php
$my_input_html="Enter string: <input type=\"text\" value=\"\" name=\"serendipity[template][txtstring]\">";
$template_config=
array("var"=>
"my_html",
"type"=>"content",
"default"=>$my_input_html
);
?>
You will be able to access it in smarty using $template_option.txtstring !
Image selection via the Media manager
Image selection via the media manager isn't difficult at all. Looking at the serendipity source code responsible for allowing you to pick images associated with a category shows how it all works. [s9yroot]/include/admin/category.inc.php gives you the answer:
<script type="text/javascript" language="JavaScript" src="serendipity_editor.js"></script>
window.open(\'serendipity_admin_image_selector.php?serendipity[htmltarget]=img_icon&serendipity[filename_only]=true
-
Apart from the inclusion of serendipity_editor.js the important bit is the new window command and its location argument:
- serendipity_admin_image_selector.php is the filename of the media manager.
- serendipity[htmltarget] specifies the target id of the input box that will take the media file path. In this case it is img_icon . This is another reason why we need to use the content type option in the $templates array to insert our own form code. Serendipity generated form elements do not have an id.
-
serendipity[filename_only]=true tells the media manager that only the filename is wanted and not the whole HTML code stuff that you get if you want to insert an image into a blog post.
Duplicating this code we can now display our own media manager window and store and use the returned file path.
Part 2: Making it work in your own templates
As a template developer I will need to add header image selection via the media manager as an option to a number of my templates. Therefore it makes sense to create a general and easy to use script that will generate the required html that I can simply add to the $template_config array as a content type. That is exactly what I did with functions.custom_imgsel.inc.php and custom_imgsel.js which were used to provide this feature in both beautiful day and now freshy. You can download both files here. Unzip them and place them inside your theme's directory.
Generating HTML
You will have to include functions.custom_imgsel.inc.php in your config.inc.php. But before you do that you will have to check the s9y version to make sure it is 1.1 or higher. This is required because functions.custom_imgsel.inc.php makes use of some s9y 1.1 specific features. You can check the version like this:
<?php
{
//insert the rest of the code here
}
?>
The rest of the code will go inside that if block. Include functions.custom_imgsel.inc.php :
<?php
include(dirname( __FILE__ ).
"/functions.custom_imgsel.inc.php");
?>
Then call custom_output_script () to generate the js code:
$header_js=custom_output_script();
The function custom_imgsel() is used to generate the HTML. It takes two arrays as arguments. The first array defines the variable name, heading and description that is shown to the user:
"var"=>"myheader",
"heading"=>"Header image",
"description"=>"Please choose a header image"
);
To refer to the user's choice you will use $template_option.myheader in smarty. But more on that later.
The second parameter for custom_imgsel() is the options array. Most themes will include their own header images. You will define them in the predef sub array of the options array. You will also specify a label for the custom image selection input field:
"type"=>"radio",
"predef"=>array
(array("val"=>serendipity_getTemplateFile
("/img/default.gif"),
"description"=>"Default header image",
"preview"=>true
),
"description"=>NONE,
"preview"=>false
)
),
"custom"=>"Custom header image"
);
Whew! Ok lets start at the top. type is used to specify what form element will be used to display the list of predefined header images. You have two options radio or select.
predef is an array in which you define various included header images that the user can select. It can be empty if no header images are included with the theme. Each predefined header image is a sub array. The val key is used to specify the value stored in the db and made available via $template_option.myheader in smarty. It will usually be the path to the header image. serendipity_getTemplateFile, BTW, is a function included with s9y that just returns the http path to the file. description is the text the user sees and preview is used specify if its an image that can be previewed from within the admin suite.
custom is used to specify the label for the custom header image input field. In smarty you will refer to the value of this input field using $template_option.custom_varname. In the example presented above it will be $template_option.custom_myheader .
Next just call the custom_imgsel fucntion with these arrays as arguments:
$header_html=custom_imgsel($header_text,$header_option);
And add the generated html as a content type to your $template_config array:
<?php
$template_config=
array("var"=>
"my_header_html",
"type"=>"content",
"default"=>$header_js.$header_html
);
?>
Referring to user input
The following is an example of the sort of logic that you can use to respond to the users selections
{if $head_version>=1.1}
{if $template_option.myheader!=''}
{if $template_option.myheader=="custom"}
<!--show custom header-->
<img src="{$template_option.custom_myheader}" /> {elseif $template_option.myheader!="no"}
<img src="{$template_option.myheader}" /> {/if}
{else}
<!--- default header -->
<img src="/path/to/default_image.jpg" /> {/if}
{/if}
The above code is just an example. The key points to note are:
- $template_option.myheader will contain the path of the predefined header image that the user has chosen
-
If the user chooses to use a custom header image, possibly selected via the media manager then $template_option.myheader will have the value "custom" and $template_option.custom_myheader will have the path to the custom header image.
So there you have it. Now you know how you can add easy image selection to your s9y templates configuration.
