Design Integration Guide

Design Integration is the process of turning a new default Silk website into a custom-designed website your client can update.

Important: Please read the Getting Started guide before this document.

This guide is aimed at web designers who are familiar with HTML and CSS. Silk websites can either be customized with your own HTML and images, or by using an existing web design template.

Introduction

Silk provides an entirely new way to turn a great looking static website into a powerful dynamic website that is easy to extend with new features for years to come.

When you order a new Silk website, you'll be presented with a default layout which must be customized (or integrated) with your own unique graphics, HTML and CSS before it can be presented to your client.

This guide covers the process of integrating a new default Silk website into a custom-designed website your client will love. Exactly how long this will take will depend upon the complexity of the design, but as you become more experience with the way Silk works you can expect to complete the process within 20-30 minutes for most website designs.

What will I need?

Design Integration can be carried out entirely with a web browser, but you will find the whole experience a lot easier if you also connect to your new Silk website over SFTP. This will allow you to upload your images and other files much faster.

Silk is designed to work with all major web browsers, but we highly recommend working with Firefox for three key reasons:

Web Developer Plugins. Firebug and the Web Developer Toolbar are two amazing Firefox extensions that can be freely downloaded from the Tools>Add ons menu. Together they give web designers and developers an amazing set of tools to aid with CSS, positioning and HTML validation.
Better HTML formatting. Due to unavoidable quirks inside Internet Explorer's DOM model you will find all of your nicely formatted code is stripped of all excess whitespace whenever you switch between code view and the Visual Editor. Firefox will keep your tabs and spacing in tact.
Better JS Performance. Javascript runs much faster in Firefox than IE, which is useful when you're viewing our interactive tables of data.

Understanding Layouts

Let's get started by discussing the most important design concept within Silk: Layouts.

Think of layouts as templates for your pages. You can create as many layouts as you wish, but most website will only ever require one. Each layout exists as a separate file inside the /app/views/layout directory and ends with the .rhtml extension.

By default, each new Silk websites comes with one default layout called application which can be easily customized to your design You can view the contents of this directory either by hovering over the Files menu, selecting Layouts and clicking on the file, or by accessing it via SFTP.

Layout files should contain anything you want to appear on multiple pages, outside the main content area of the page. Typically this will be the website's logo, tagline, navigation and footer. If you want something to appear on most pages but not all, for example a sidebar continuing opening times, it is best to leave it out of the layout and deal with it on a page-by-page basis using sections and snippets (we'll get to those in a moment).

You can specify which layout file each page should use in the Main tab of the Page Properties. Every page will use the application default layout unless instructed otherwise. For most simple websites this will probably be the only layout file you'll ever need; however more complex websites may require several layouts.

Occasionally, you won't want to use layouts at all - for example, if you need to make a popup window. In this case, all you need to do is set the Page Layout to false.

Remember the layout often includes the opening HTML, HEAD and BODY tags. If you choose not to use a layout, you will have to include these within the page.

Editing the default layout

Start by opening up the /app/views/layout/application.rhtml via the Web Admin interface or using any good text editor over SFTP.

Tip: You may want to take a backup of the file before you begin!

The default layout contains minimal HTML code, so you will want to start customizing this to suit your needs.

Introducing ERb Tags

You will notice the default layout contains a number of weird looking tags which are probably unfamiliar with. These are called ERb tags and are one of the most powerful features of Ruby on Rails (the web framework used to create Silk).

We give you the full and unrestricted power of ERb inside all the layouts and every page by default for maximum speed and flexibility. Luckily you don't need to have any prior knowledge of ERb or Rails to use Silk, but we do want to cover a few of the basics here.

ERb tags start like this <% and end like this %>. Anything contained within an ERb tag is a command which will be executed by Silk each time the page or layout is loaded.

Most of the ERb tags you will come across will output the result of the command directly to the screen. Hence these tags contain an additional equals sign <%=.

ERb Tags within the Layout

For the most part, your layout files will contain regular (x)HTML code. However, there are four key ERb 'tags' which must be inserted in the correct place to allow Silk to work its magic:

<%= page_title %>: This tag should live inside the HTML <title> tag. It will automatically insert the correct Title for the page, as specified by the end user.
<%= page_headers %>: The page headers tag allows Silk to insert meta tags along with links to stylesheets and javascripts when needed. It must live inside the HTML <head> tag.
<%= page_body %>: Like page_headers, the page_body tag allows Silk to insert code required by the system. It must be called directly after the HTML <body> tag.
<%= page_content %>: This is the most important of all tags as it outputs the main contents of the page - whether the page is a 'real' page you have created or part of the Silk application. It must also live inside the HTML <body> tag.

Here's an extremely basic layout showing the tags in action:

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title><%= page_title %></title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> 
<%= page_headers %>
</head>

<body>
<%= page_body %>
<%= page_content %>
</body>

</html>

Page Sections

Some layout designs require more than one area of editable content. For example, you may have a sidebar which is used to display related information to the main content.

The best way to describe Page Sections is as placeholders for future content. You can define as many Page Sections in your layout as you wish, providing each one has unique name. For example, to add a Page Section called 'Sidebar' you would include the following tag in your layout:

<%= page_section('Sidebar') %>

Simply adding the page_section tag into the layout will not change the page output until you explicitly use this section within a page as so:

<% section('Sidebar') do %>
  Example content for the Sidebar goes here.
<% end %>

That's all there is to it!

Tip: If you need to show the same content over several pages, just include a Snippet in the section code.

CSS Files

Although there is no requirement to use CSS, your website will be much easier to maintain if you follow a few simple conventions used by Silk.

By default, Silk uses three CSS files which are all stored in the /public/stylesheets directory.

content.css: This file should contain all styles which apply to the content the client will be creating. All classes included in this file can be selected by clients using the drop-down menus inside the Visual Editor.
layout.css: Use this file for controlling the non-content aspects of the site - like the logo positioning or navigation styles. Classes listed in this file will not be available inside the Visual Editor.
system.css: This file allows you to overwrite the default Silk system CSS classes. It is called after the main system.css and theme.css are loaded, but only when you are logged in. Of course, if you and the client are happy with the way the standard Silk interface looks you will not need to edit this file.

It’s worth pointing out that all CSS files are cached on the client’s computer so the browser will not be making multiple requests to the server every time a page loads.

Tip: Silk deliberately uses standard HTML attributes for headings, so changing the style for H1 inside content.css will automatically change the headings of pages inside the Silk interface.

Outputting additional Page Headers

From time to time you will want to insert your own page-specific code inside the <head> tag. This can be done easily by calling page_header followed by anything you want to output.

For example, to include a custom CSS file within your page, just include the following:

<% page_header stylesheet_link_tag('example.css') %>

Or to include a custom Javascript file within your page just type:

<% page_header javascript_include_tag('example.js') %>

Note there is no equals sign after the start of the ERb tag as we are not outputting anything in the current position, but rather in the headers of the page.

Of course, your CSS and JS files could live anywhere within the /website/public directory, but putting them in their respective folders allows you to call them without specifying the directory.

Themes

Once the layout(s) has been created, the CSS sorted and the images uploaded you may find the default sky_blue color scheme looking a little out of place with your design.

Thankfully it's easy to choose another preset color scheme for the Silk interface by visiting the System Setup page at /admin/system. You will need to type the URL in directly as there is (deliberately) no link from the Admin Menu as this is not a page your end users will need to visit.

Please note: It is already technically possible to create your own color scheme or completely independent theme, but we need to do a little more work to make this process as easy as it should be! Please contact us if you require assistance.

Solving common problems

Hopefully after following this guide your new website is looking good and everything has gone to plan. However, if you're having difficulties, here are a few possible problems you may be having:

CSS 'Pollution'

Because the Silk web interface runs inside your website, it is possible that some of your own CSS styles are interfering with those used by the Silk interface. We do our best to explicitly define all the styles used in the Silk interface, but sometimes things can slip through the net. This problem can be avoided completely by always targeting styles using classes or IDs, but if this is not possible, please get in touch with us and we will find a solution.

Insufficient width for Silk Interface

The Silk interface requires a minimum width of approximately 800 pixels to function correctly. Most website designs will be able to comfortably support this, but if your default layout has a particularly narrow space for content, there is a simple solution.

Background image pushed out of place by Admin Menu

This will occur if you have assigned a background image to the BODY tag using CSS. If this image is non-repeating and plays an integral role to the positioning of the site you may need to remove it from the BODY tag and assign it to a DIV tag called directly after the page_body ERb tag.

Adding Features

By now you have completed the integration and should have everything looking how you want it. It's now time to visit the Recipe Guide and add some dynamic features!