Creating Installable Templates for ExpressionEngine 2
Posted in Template Code Tutorials
This is the second installment in our Creating installable templates tutorials for ExpressionEngine. In this post we are going to talk about the actual package that needs to be delivered to the end user and all of the associated files. Plus we even have a bonus of some useful code for you.
Before you get started it may be helpful to download one of our templates (free) to help follow along
Special thanks to Greg Salt from Purple Dogfish for his help on the default content file code
Folder Structure and Files
I still prefer to to keep my CSS and JS files outside of EE so the root of my package has a css and a js folder (if I am using Javascript for anything). I also have an images directory and a themes directory. Obviously you need to warn the user not to overwrite any core files they may have uploaded as part of the default EE install.
The real magic happens inside of the themes directory. Inside of the themes folder I follow the same path that the user would have to follow in order to upload the theme and have it work on their server. So the path will be themes/site_themes/theme_name where theme_name is the name you want for the theme. For the purposes of this tutorial let’s call the theme Tudobem (one of our previously released templates). So your path would be themes/site_themes/tudobem
Inside of the tudobem folder you will have a mixture of folders and files. Let’s talk about the folders first. One of the really nice features of ExpressionEngine 2 is the capability to create a folder called site.group and have EE make a new template group called site. Inside of the folder you will want to create an index.html which will create a new template in ExpressionEngine called index. Following this same example if you want to have a blog section for the template you will have a folder titled blog.group that has files in it titled index.html, comments.html, archives.html, categories.html and so on.
If you have created a site in EE2 and want to speed up the process you can just synchronize the files on the server and the system will output of the .group folders for the various template groups and the .html files needed for the various templates. So you are 75% of the way there.
In addition to the .group folders you will want to have a snippets (snippets) and a global variables folder (global_variables). Note that they do not have the .group naming convention. From my experience the files in the global_variables and snippets folder have no extension. So if you wanted to create a new snippet that contains an Email Address just title the file email_address with no file extension, and put the demo email address inside the file.
Now let’s park on snippets for a minute. We talked in the previous blog post about how Global Variables and Snippets are parsed at different times and that if you want to be able to act against the data as part of a conditional statement it needs to be a snippet. So if you are building a template and you want to make it really easy for people to update it then you can create snippets for email address, company name, fax number, address, template color, google map code, fax number, phone number, etc etc. So when someone installs the template all you have to do is direct them to the snippets area in the control panel and they can update all of the business pertinent information without having to modify the templates.
If you’ve looked at the Agile Records example you know that there are 2 files inside of the theme’s folder. The first we will discuss is the theme preferences file. This file just tells you what modules you want installed, what some of the preferences are for some of the templates. Can certain member groups access certain templates? This is where you would set it. This file is pretty simple. If you have questions pose them in the comments as I will gladly expand on this but it seems pretty straightforward.
The more interesting file is the default content file. I’m about to make your life a whole lot easier… In the example for agile records you would have to go through the database and remove all non pertinent data but leave all tables that are needed to complete the site. This would be everything from the exp_channels to the exp_categories table and all of the associated data. If you want to make everything a little bit easier then you will just use this bit of code inside of the default_content.php file…
code<?php
$original_url = '**Insert the URL to your demo install here**';
$tables = array(
'exp_categories',
'exp_category_fields',
'exp_category_field_data',
'exp_category_groups',
'exp_category_posts',
'exp_channels',
'exp_channel_data',
'exp_channel_fields',
'exp_channel_titles',
'exp_comments',
'exp_fieldtypes',
'exp_field_formatting',
'exp_field_groups',
'exp_global_variables',
'exp_relationships',
'exp_snippets',
'exp_statuses',
'exp_status_groups',
'exp_templates',
'exp_template_groups',
'exp_upload_prefs'
);
$thepath = '../themes/site_themes/**Insert your theme folder name here**/template.sql';
$template = file_get_contents($thepath);
$pattern = "/^(CREATE[ A-Z]+`(".implode('|', $tables).")`.*);/Ums";
preg_match_all($pattern, $template, $matches);
foreach($matches[2] AS $table)
{
$this->db->query("DROP TABLE ".$table);
}
foreach($matches[1] AS $sql)
{
$this->db->query($sql);
}
$pattern = "/(^INSERT[ A-Z]+`(".implode('|', $tables).")`.*);\\n/Ums";
preg_match_all($pattern, $template, $matches);
foreach ($matches[1] AS $sql)
{
$sql = str_replace($original_url, $this->userdata['site_url'], $sql);
$this->db->query($sql);
}
In the above example you will need to modify it per template in two places. The first is on line 3:
$original_url = ‘**Insert the URL to your demo install here**’;
The original URL may be an actual URL like http://demo.eetemplates.com/tudobem (doesn’t exist anymore but that is the old location) or it could be on your localhost if you developed the template locally.
The second location you will need to make a change is line 28:
$thepath = ‘../themes/site_themes/**Insert your theme folder name here**/template.sql’;
Obviously your folder name will not have any spaces in it. An example might be:
$thepath = ‘../themes/site_themes/tudobem/template.sql’;
If you are a PHP developer and you think you can expand or fix something in the above code then please contact me. I would love to see a robust theme installer be built for EE. If this code can be the seed for that then so be it.
What you do next is take a sql export of your database and place it into the final file we need to discuss which is the template.sql file. Make sure to synchronize the templates before exporting though. And also make sure that you change your password for the template before exporting. I would imagine if you wanted to you could also use a tool like Deeploy Helper from Hop Studios and change all of paths in the template and then export it. Just depends on how far you want to take it. So export your database. Make a file called template.sql and paste all of the exported sql into the file.
Now all that is left to do is test the install. I typically do this a couple of times just to make sure. You are bound to find some things that are wrong. Perhaps you forgot some files. Or you forgot to sync the templates prior to exporting. Or you messed up the folder names in the default_content.php file. Whatever it is just keep reinstalling it till it works 2x without issues.
As part of all of my templates I always take the time to create a readme.txt that typically has basic instructions in it of what to upload where and license.txt file in the root of the main folder. You might also have source photoshop files. Make a folder called Source Image Files and put all of the .psds or layered .pngs in this folder. More power to you if you want to include a fully outlined pdf of how to install the template.
Then just name the main folder something meaningful and zip up the package. Oh… and don’t forget to send us a copy to post here for all to see.
Want to write a blog post? Just use the contact form on the submit page!
Comments
Tell us what you think...
Related Articles
Learning Things the Hard Way - Upgrading from 1.7 to 2
This is just a quick blog post to relay some info I just learned. I am in the process of upgrading Show-ee from 1.6.8 to 1.7 and then to 2.1.4b. As part of that site we used to use FieldFrame from Pixel & Tonic. Specifically we were using the
Removing Index.php from the URLs of Expression Engine websites
For a long time now I have struggled with removing index.php from my EE websites. I have used a mix bag of the include/exclude method and add-ons that deal with making the include/exclude method easier.
Creating your own installable templates for ExpressionEngine 2
A year ago I was perusing the user guide and wiki over on ExpressionEngine’s website for any information regarding creating your own installable templates. At that time there were none. At I just did a quick search for some of the files involved
An Introduction to Fireworks
In this video we will start with a blank slate and create a usable but simple layout to replace that which is found at Sean Smith’s Repatriate.me. This was not meant to be a end all be all tutorial but rather just a quick post about some of the
Be the first to leave a comment...