Converting v2 Themes to v3

Before we begin

We will be converting a fairly simple theme from v2 to v3. For this tutorial I am going to assume you have at least a basic knowledge of CSS and HTML. If you don't feel comfortable with this, most of the v2 themes were already transferred to v3, and they can now be quickly and easily customized under Project-->Distribute-->Default Theme--> Themes. For more on this, check out our customizing the look of your survey tutorial.

If you're still with me we will be converting over the "Forest Greens" theme from v2 to v3. As mentioned above: This has already been done for you, so conversion is just to highlight what has changed between v2 and v3 themes.

Editing HTML and CSS can be done with any text editor on your computer, but I suggest these 2 great (and free!) applications: TextWrangler for OSX or Notepad++ for Windows. If you need to make some simple edits to images try out the free web-based Piknic. When you're building the themes your best friend will be firebug; go get it now if you don't have it!

What's Changed?

• HTML Merge Codes

  Question Merge codes have changed all through SurveyGizmo v3. They changed to be more stable, easier to understand, and more consistent system wide. In the same way, Template Merge Codes (Both HTML and CSS) have gone through some changes as well.

  v2 Merge Code	v3 Merge Code	Notes
  [%%:ImageLink_1: A URL to your Logo/Header Image (Default: https://www.surveygizmo.com/images/spacer.gif)%%]	[template("header image url")]	If no image is supplied a blank spacer.gif will be supplied without needing to define it
  [%%:CustomText_3:Logo Alt Text(Default:Logo)%%]	[template("header image text")]
  [%%:Survey_Title%%]	[template("survey title")]	The new merge code now outputs: <h1 class="sg-title"><span>Survey Title</span></h1>
  [%%:Page_Title%%]	[template("page title")]
  [%%:Error_Message%%]	[template("error message")]
  [%%:Page_Description%%]	[template("page description")]
  [%%:Question_Block%%]	[template("page contents")]
  [%%:Button_BackPage:Click to Go Back%%] [%%:Button_NextPage:Click to Next Page%%] [%%:Button_Submit:Finished? Submit your Survey%%]	[template("button bar")]	The Button Bar merge code now replaces all three v2 button merge codes.
  [%%:Survey_ProgressBar%%]	[template("progress bar")]
  [%%:CustomText_2:Footer Text (Default: )%%]	[template("footer text")]

• CSS Merge Codes

  With CSS Merge Codes you can define certain colors or display settings in your theme that can easily be changed while building a survey. As an example, you could create a theme for a set of sports teams, and while building the survey change the colors to match an individual team without touching any CSS. We'll cover more specifics below.

  The Color Mixer

  This is a specific type of CSS Merge Code where you can define 2 colors and how you want to mix them. The real strength of this code comes when combined with other CSS Merge Codes. When you combine these merge codes you can combine 2 different dynamic colors or create different shades of one user set color.

  Example: [template("color mixer"), from="body background color", to="page background color", amount=".75"]

• The Theme Library

  In v2 when a theme was applied to a survey that theme was static. To update the theme you had to go into the survey itself and make changes to the HTML or CSS, or reapply the changed theme and loose any local changes.

  In v3 we made this entire process much smarter! Now, themes are individual entities, separate from the surveys they are applied to, that live in the theme library. In a survey you can further customize a theme with the help of the previously mentioned Merge Codes or by appending CSS changes to the survey.

  In practice this means that you can make changes to a theme, and those changes will propagate out to all of the surveys using it. Customizations on individual surveys (colors, survey width or appended stylesheets) will not be overwritten.

• Page Structure and Margin/Padding

  We changed the HTML structure of our line of default themes (Modern Blue Grey, Green Tea, Smoke and so on). We also changed the default naming or each <div> from an id to a class. What was id="sg_header" is now class="sg-header". Keep this in mind if some of your styles don't appear to map to your HTML.

Copying your theme

Excellent! Now what we covered some of what's new in v3 we can get down to converting your v2 theme. We have 2 choices on how to go about doing it: rebuilding your theme in v3, or using your old code from v2.

Rebuild it in v3 or...

Essentially for this approach you will create a new theme in v3 and rebuild your old theme from the ground up. This will be the best approach for learning about the new CSS merge codes and making sure you have clean code to begin with.

...change your v2 theme

1. Move the code to v3 (Copy and paste the code from V2 to a V3 theme)

2. Begin by finding the theme you want to convert in v2. This will either be tied to a specific survey, or in your Theme Library. Copy both the HTML and CSS into a text editor of your choice. Make note of any other settings that are important to our theme.

   In v3 we want to take advantage of the cool new features of the Theme Library so we'll begin there. Click Libraries > Themes > Create New Theme. Now name your theme and copy all your v2 theme code back over to the HTML and CSS text boxes.

3. Replacing HTML merge codes

   

4. Let's update those old merge codes to full v3 spec. Look for any of your old merge codes, recognizable by their '%%' marks. Replace them with the new merge codes by copying and pasting in place of the old merge code in your HTML.  If you can't remember the merge codes, check out the Merge code table at the top of the post. Repeat this for every old merge code in the HTML. Remember that the navigation button merge codes have all been replaced with just [template("button bar")], and [template("survey title")] now contains the H1 and span tags.

   Save your theme!

5. Replacing CSS Merge Codes

   Scan through your CSS code for merge codes like you did for your HTML. When you find them follow the same procedure to change these. [%%:Font_1: Font Family (Default:"Century Gothic","Avant Garde","Gill Sans","Lucida Grande","Lucida Sans Unicode",verdana)%%] will become [template("base font family")] and so on for font size and width.

   At this point you can further customize your theme by picking the most common colors and inserting merge codes for them. In our Forest Greens example this:

   .sg_Body {
   	background:#757D41;
   }

   gets changed into this:

   .sg_Body {
   	background:[template("body background color")];
   }

   The amount of color merge codes you enter into the CSS defines the level of customizability in that theme. The more you CSS Color Codes you enter the more your theme can change later without having to touch code.

   After the merge codes are in your CSS you need to set their values with the settings panels to the left.  All colors should be set, even if there are no merge codes in the CSS for colors because some question styles use those Merge Codes in conjunction with the Color Mixer to blend in with your theme.

6. In our example Forest Greens theme the CSS Merge Codes panel looks like this:

   

7. Test and see what's broken

   Save and Preview. If you're following along with this tutorial it should look pretty good so far with only 2 big problems: the background color isn't there and the back/next/submit buttons are missing styles.

   The background isn't getting applied because the class "sg_Body" from v2 changed to "sg-body" in v3. Let's change that in the CSS, and fix the margin/padding so that rule looks like this:

   .sg-body {
   	background:[template("body background color")];
   	margin:0px;
   	padding:0px;
   }

   Buttons don't have their old styles for much the same reason. The old classes: "sg_Submit", "sg_BackButton", and "sg_NextButton" should all be changed to "sg-button". Here's the updated code:

   /* Buttons  */
   .sg-button 
   {
   	height:40px;
   	border:1px outset #000 !important;
   	background: #fff url(https://app.sgizmo.com/images/surveys/btn_grey_gradient.gif) repeat-x 0 0;
   	font-size:120% !important;
   	padding: 1px 15px;
   	}
   .sg-button:hover {
   	background: url(https://app.sgizmo.com/images/surveys/btn_grey_gradient.gif) repeat-x 0 -40px;
   }

8. Final Test

   Your Theme may be good to go as is, but to really make sure it's a good idea to construct a survey with all the different question types and run one final test. If you can't read something because the text color is too similar to the background color it may be that you didn't set all of the colors in the CSS Merge Code Panel.

   Some specific question types to test are:

   • Drag drop Ranking
   • Tabels
   • The calendar for the date question type
   • File upload and the File upload confirmation message
   • Save & Continue

You're Done! And now you have a solid enough understanding of the new theme system to go on and create brand new themes in v3. Enjoy!