The -xmedia hint allows you to easily incorporate complex external html files into your Photoshop designs. (You can place smaller quantities of less complex HTML directly in the Photoshop document using the -literal hint instead.)
This feature is very powerful but must be used carefully. Invalid, poorly formed HTML files that are imported using SiteGrinder Pro can ruin the display of your pages in many or even all browsers.
This document discusses some of the considerations when importing external HTML.
Use Correct HTML
SiteGrinder performs no validation on the HTML files it is given as sources.
SiteGrinder builds XHTML 1.1 valid pages from Photoshop designs. All of your source external HTML should also be XHTML 1.1 valid.
If they are not you run several risks:
- Invalid external HTML will cause SiteGrinder’s HTML to become invalid as well.
- Invalid HTML may put the browser into “quirks” mode. This could severely impact page layout.
Please use http://validator.w3.org to validate your source HTML files.
The Three Styles of Importing
SiteGrinder Pro allows you to import HTML in three different ways:
- Standard
- PHP require()
- HTML Object
The method is set using the External Media pane of the SiteGrinder window. Clicking in the "Type" column next to an -xmedia layer presents a dialog for choosing settings including the type of HTML import.
Each type has its advantages and disadvantages, as described here:
Standard
Standard HTML import places the contents of the HTML file into the page as it builds to produce a final page.
PHP require()
This technique does not import the HTML when the page is built. Instead it inserts a PHP require() command into the document to include the entire file each time the page is loaded from the HTML server.
Your web server must support PHP for this to work and PHP must be turned on. Unless you have a local PHP server you will not see a preview of the imported HTML until you upload the site. You can test your server from the SiteGrinder window's report pane if you have set up your server information in the settings panel.
Some PHP servers also require that pages using PHP must in the .php extension instead of .html or .htm. In this case you can change the page's file extension using the Pages pane of the SiteGrinder window.
Because PHP require() includes the entire document that is referenced, it is presumed that the document is an HTML fragment, not a full document. The document should not have <html>, <head>, or <body> tags.
If the external .html file is in the build folder, it is directly included by a <?php require() ?> statement. Otherwise, it will receive the same file and links handling as is described for HTML files below (but not CSS or Javascript handling).
The advantage to this technique is the ability to edit only the text of part of the page (the external file) and re-upload only that text without having to rebuild anything from SiteGrinder. This is perfect for a "news" section or changing restaurant specials.
HTML <object>
The HTML <object> technique works much like PHP require(), but with two key differences:
- HTML <object> doesn't need your server to support PHP.
- Where PHP needs HTML fragments, HTML <object> needs a full HTML file
The downside is that this technique cannot use the -grow hint. Whether you add the -scroll hint or not there will be a scroll bar drawn with this content in almost all browsers, even if scrolling is unnecessary.
Beyond the HTML Text
SiteGrinder includes the contents of the external document’s <body> tag into the –xmedia placeholder. The other elements of the document receive custom handling, so that the integrity of the external HTML document is preserved, as described below.
Links
SiteGrinder will remap some links in your included HTML file.
If the file is in the external media folder and it links to another HTML file that is in the external media folder, then SiteGrinder will find the SiteGrinder page that is going to include _that_ HTML file, and if found will change the link to that page.
Thus, you can have HTML files in the external media folder that all link to one another, and once they are incorporated into the SiteGrinder pages (i.e. ‘skinned’) then their links will still work.
CSS
If the file has a <style> section in the <head> then that CSS will be parsed and incorporated into the SiteGrinder style output. Styles shared between multiple external HTML files may end up being in the common.css file.
SiteGrinder will properly scope any style inclusions, to protect the integrity of the overall document that it builds.
Javascript
Any javascript used by the HTML files in the external media folder is dutifully transcribed to the <head> of the new SiteGrinder HTML file.
File references
If the HTML file references other local files (images, other html files, other media, etc.) then those files are copied into the page's external media folder and the paths updated.
This includes javascript files, image files, non-xmedia HTML files, and more.
