An HTML Package section allows you to add almost any kind of interactive content you can think of to a Zoomforth site section. A Zoomforth HTML package is created by creating a special .zip file. The following will guide you through creating a Zoomforth HTML package, uploading it to Zoomforth, and using it to create an HTML package section.
Be aware: An HTML Package is just a mini-webpage, so you need to have significant knowledge about how webpages are built to create one.
Use cases
Build custom HTML apps
Create interactive tutorials
Embed custom widgets such as Twitter timelines, custom forms, or commenting platforms
What you need to know
HTML, Cascading Style Sheets, and JavaScript knowledge
How to create a .zip file
Requirements
Compress all files needed for the content into a .zip file
You MUST have an index.html file in the .zip file
The index.html file, if referencing other files in the zip file, must use _relative references_ (e.g.,
/foobar.img, nothttp://example.com/foobar.img)
Some tips for success
Only HTML, JavaScript, Cascading Style Sheets and media files are supported
Flash should be avoided as it is not supported on all platforms
Avoid spaces and special characters in files and folder names
Don't use
iframesin your contentYou should use HTTPS for all external links and media
Optimize and profile your HTML content in cases where loading time is important, (don't use a huge PNG image, where a JPEG might be appropriate)
Preparing your content
Before you can add your content to Zoomforth and use it in sites, you will need to prepare the content so it can be uploaded successfully. In the simplest solution, you need to make an index.html file, place it in a folder, and compress that folder as a .zip file.
If you are using a third-party application to build your content, you should find out if you can export it as a .zip file or an HTML application. Most third-party applications give this option but if you cannot find it you can check with their support team for options. You should check the exported package and and ensure that it has an index.html file in the root of the .zip file.
Another way to get content is from a custom widget. A lot of websites will let you generate a snippet of HTML (such as Twitter or Disqus) and use that in your website.
To use that as an HTML Package:
Copy the HTML snippet from their website
Create a new file called index.html on your computer
Paste the HTML snippet into this file and save it
Right click the file and compress it as a .zip file
One thing to note is that if the content is hosted somewhere else and you have a URL to it, consider using the Custom Embed section in the site editor to achieve a simpler solution.
Uploading your content
There are two main ways to upload your HTML package to Zoomforth: from the media library and from the site editor. In both instances Zoomforth will upload the .zip file, unzip it, and upload the individual files. We then use the uploaded index.html file as the source for an iframe in your sites.
To upload an HTML Package through the media library, you can click the + Upload Media button in the top right corner. You will see a new screen that looks like the one below.
Click on Add HTML Package and you will be prompted with another screen to upload your content. Click the Upload .zip file button and you will be able to select your .zip file from your computer. You will see your content processing in the media library after you select it. Once done, you can preview the content by double clicking on it in your library.
In the Site Editor you will see a new section type called HTML Package.
When you click the new section type, you will see a screen similar to the one in the media library.
Selecting content from the media library will create a new section based on the HTML Package you have already uploaded. If you choose to upload a new HTML Package then it will upload and process the files in the editor before creating your new section.
Like other sections, you will have some options to manage the content in the editing panel on the left side of the screen.
You can change the section content by replacing the HTML Package. One interesting thing to consider is how the HTML Package will behave on mobile. If the content was built to be responsive based on screen size then you should show it on mobile. If it does not look right on mobile you can also hide the content completely. You can always preview what your site looks like on mobile by clicking the phone icon in the top right corner of the site editor.
Adding third-party tracking
Zoomforth does not track interactions that happen within your HTML Packages. If you do need insight on interactions you have two options: you can build a custom solution or use something like Google analytics. Custom solutions will require you to have a place to send data to and process it. This is an advanced use case and is best left for development teams to solve.
Google Analytics can be a simple solution for tracking events. You can add your Google Analytics embed code in your index.html file and everything should be sent to your Google account based on how you set it up.
Automatically set height of section
One limitation with HTML Packages are that they are served in iframes. If you find that scrollbars are appearing then you have a few options. For one, you can set the height of the section or set the section to full width in the site editor. This will help but you may notice some screen sizes which still show scrollbars. If you would like the section to automatically set its own height then you can add the following code to the body of your index.html file.
<script type="text/javascript">
function getHeight() {
return document.getElementsByTagName("html")[0].scrollHeight;
}
function sendMsg() {
var msgData = {
height: getHeight(),
url: window.location.href
};
parent.postMessage(["setHtmlPackageSectionHeight", msgData], "*")
}
window.addEventListener('load', sendMsg);
var resizeTimer;
window.addEventListener('resize', function() {
clearTimeout(resizeTimer);
resizeTimer = setTimeout(sendMsg, 250);
});
</script>
The above code will communicate with your Zoomforth site and set the height of the HTML Package section automatically so the entire contents fits. It will also adapt if the screen size changes.
NOTE: This code will not work for tiles in a grid. This is due to how tiles are sized based on screen size. Changing the height of a single tile could affect layouts and deprecate the site editor behavior.
If you need further instructions, or you need someone to evaluate your HTML Package, please reach out to support for help.
Limitations
HTML Packages are loaded into an iframe in the site. You will not be able to interact with other elements such as tiles from this iframe.
All external links to content in your site should be done over HTTPS. Any links that do not start with https:// may be flagged as insecure content. This is because we serve the HTML Packages over HTTPS and browsers require all content in that site to be secure.
HTML content best practices
Check the size of your HTML Package content. If it is loading slowly it could be loading a lot of additional scripts and styles that may not be needed.
If you are using external libraries like jQuery then understand the performance hits it may cause. If you don't need the library then remove it from the .zip file and index.html file.
Cascading Style Sheet animations can be more lightweight than JavaScript animations.
Don’t develop for a fixed viewport, not all devices are 1024*768 and devices can be rotated. If the content needs to be user landscape or portrait, be sure to add a message when used incorrectly.
You can set the overflow of the section iframe to play with scrollbars.
When using relative links to files in your HTML Package, make sure that they go to the correct place and use the same names as the files. In some operating systems uppercase and lowercase matters.
If you want to save the state of content, such as a tutorial, consider using localStorage or saving it to an API that you control.
For more information, Zoomforth Support is always ready to help.