The Homeflow system uses various levels of caching amongst other techniques to deliver content super fast to the user’s browser. That being said, there is no substitute for coding your theme in the most efficient way possible. Google has an excellent tool called PageSpeed Insights that you can use to review your site.
At Homeflow we like to keep our code base nice and clean and well organized, this is important when designing a theme to be used on the Homeflow platform.
You should aim to keep your files small and concise, and to reuse code where possible using partials. For example, you may create a property partial which is reused in multiple areas throughout the site, not just the property pages. However, using too many partials (especially ones buried deep in the folder structure) can make a project difficult to read and navigate, especially for someone coming to the code for the first time. Bear this in mind and try to organise your code while keeping it readable.
You should also aim to keep your HTML and CSS code as clean as possible by removing unused or unnecessary code and formatting and indenting the files sensibly.
We would also advocate the use of code analysis tools like the W3C Markup Validation Service or CSS Validator to identify and fix problems in your code.
Lint is a powerful tool which can analyze your Homeflow theme and identify problems in the configuration and setup.
We recommend using Lint regularly throughout the development of your theme, you can find it here.
Image Formats
It may seem obvious but choosing the right images are important for the efficiency of the theme and can affect the overall speed of the site.
It is advisable to pick the right type of image for the job.
BMP files should never be used. Ever.
PNG The Portable Network Graphics format was designed to be a lossless format for use on the WEB (among other things). It does reduce the size of your files. However since it preserves all the detail and all the colors the size reduction is not as much as GIF or JPG. This format is recommended for icons and small images and not large background images.
JPG. JPG stands for Joint Photographic Group, which is the name of the organization which created this format. JPG was designed for the storage of photographs and is in fact used in most digital cameras. It is lossy, so you do lose detail, but you can choose how much detail you lose.
Flexible Image Size
Images must be the number one culprit in terms of slow downloads from the server. Any image that runs through our Liquid filters will get compressed. Here’s some ways you can achieve this:
<img src="{{ portal.website_logo | url_for_portal_logo : "200x200" }}" />
<img src="{{ portal.website_logo | url_for_portal_logo : "_x_" }}" />
<img src="{{ portal.website_logo | url_for_portal_logo : "200x_" }}" />
<img src="{{ portal.website_logo | url_for_portal_logo : "_x200" }}" />Basically any size dimensions or our nifty x function will see the image pass through the filters. Also don’t forget to resize images. For example, it would be pointless dragging back a full size photo when all you need is a thumbnail for an article preview.
Re-Themeable Images
It is preferred that images are used that would not be incongruent if the theme colours were completely different. Try avoid using strong colours - perhaps using transparent icons with configurable background colours and/or white/grey shades would a good place to start.
The real world speed of a site and Google PageSpeed scores will suffer if JavaScript is block rendered in the head section. That being said, moving all JavaScript, especially library files, to the foot of a page can cause errors. What we need is a reliable way to capture document ready calls, queue them, then execute them once our deferred JavaScripts are loaded. Using our async functions, we can do just that.
To get up and running, firstly you need to set up your asset packs and vendor assets as seen here. Once done, you can render the blobs to the page with our async head and foot includes:
<head>
<link href="/vendor_assets/blob.css" rel="stylesheet" type="text/css" />
<script src='/vendor_assets/blob.js' type='text/javascript' async onload="async_foot();" ></script>
{% include 'js_templates/async_head' %}
</head> {% include 'js_templates/async_foot_function' %}
</body>
</html>We would strongly recommend integrating the async work (if you choose to use it) into your theme on inception, as re-engineering a theme to support async work can sometimes produce errors. More of often than not, this is because the deferred JavaScript isn’t ready for when some of the functions are called. To get round this, simply put your functions in a document ready.
It is best to use CSS that can be easily adapted for multiple site configurations using a range of different theme preference colours. The colour preferences page contains colours such as: primary_colour, secondary_colour, accent_colour etc and can be found in the backend at: ../configure/website/appearance/colours
These can be used in the css files in your theme as shown here:
header {
background-color: {{ theme_preferences.header_background_colour }};
}You can see a full list of the available colour options here.
When making a theme it is best to only include the base functionality that theme requires. The most logic (especially agent specific) we put into the base themes the more polluted the code gets and harder to extend/read.
You can extend from another theme by simply adding the following to the config.yml file (mentioned below in more detail):
parent_theme: ‘theme_name’
Any view, partial or file you create in the child theme will override the parent version. This means you can enhance and extend an existing theme by overriding these files.
When to use child themes
You should consider moving code into a child theme when the changes you are making are specific to a single user of your theme or it may become more difficult for your theme to be reconfigured in the future, we like to keep themes as flexible and re-useable as possible and child themes are an effective way of achieving this while still catering to agency specific requirements.
Content chunks are a very powerful tool and are used a lot in themes for all sorts of custom content. Due to the volume of these being used and the variants in each theme it is important to list them (and their description) all in the config.yml file inside the theme as shown in the section below. These will then be available in the agent backend:
../configure/website/content/site_content_chunks
The config.yml file in the theme folder is important for defining theme specific options. Below is an example of a config.yml with some common options:
theme:
name: "batty"
type: "agency_theme"
parent_theme “contador”
paginations:
- articles
default_article_topic: "winkworth"
search:
tags:
- '!archived'
enabled:
- branches_by_distance_on_locations
- searchable_keyword_lookup
- unbounded_pages
- no_redirect_on_staff_lead
site_content_chunks:
- name: 'my_cool_chunk'
description: 'A good chunk’
asset_packs:
javascript:
- application.js
stylesheet:
- main.lcss
vendor_assets:
javascripts:
- ctesius
- asset_pack
stylesheets:
- asset_packYou will inevitably encounter problems, so here are a few steps to try to resolve issues before asking for help.
Read the relevant pages in this documentation and even some of the more general pages, as the solution may be explained somewhere unexpected. Check the documentation on drops if you have a question about which variables are available from a template.
You should also refer to the Liquid documentation or Liquid for designers wiki if your issue is liquid-specific. the former contains a comprehensive list of the built-in tags, objects and filters (although, depending on the version of Liquid used by Ctesius at the time, some newer features of the language may not be available).
If you encounter a problem that isn’t specific to Homeflow’s systems and tools - but a more general programming issue, you should try to find a solution using Google or Stack Overflow. Most issues related to HTML, CSS, JavaScript and Liquid can be solved this way.
Inspecting the values of variables at different points in your code is a good way to identify where problems are occuring. You can use JavaScript to output resolved Liquid statements to the browser’s console:
console.log('Bedrooms: {{ property.bedrooms }}');JS issues are often due to the order the code is executed. Any code that requires elements of the DOM to be loaded before it runs should be placed inside one of the jQuery functions $(document).ready() or $(function()).
Ctesius.init() should be called after all config settings and event registers.
If you are unable to solve the issue yourself, ask the Homeflow dev team for help.
When asking a question, make sure it contains all the information we might need. Include the location of the file you’re working on within the project, a link to the page on the staging site, any error messages you have encountered as well as the things you’ve already tried to resolve the issue. This will give us the best chance of giving you a prompt and helpful response.
You can email us at developer-support@homeflow.co.uk