📖 Usage
The Basics
This document outlines the exact way in which the Templating Engine
looks for your content files and composes your pages. Every website built on the
BITS Framework must conform to the structure defined below.
Template
The file template/meta.html contains all tags that belong in the document
<head> across all pages. For example, linking the website icon or
the gobal stylesheet. DO NOT include a <title>
tag, this will be specified per page and injected into the <head>
as the template is composed. You should instead set the overall site name
using a <meta name="application-name" content="ABC Company Website">
tag as can be seen in the source of this page.
The file template/header.html should contain any site content that should
appear at the top of every page body. Likewise, template/footer.html contains
elements that you want to come after the main content of every page.
Routing
Actual page content goes into the pages/ folder structure.
This site acts as a basic directory structure with various tests and examples
to use as a baseline and guide your implementation. URLs are written as
rootpath/?pagename where pagename refers
to either the file pages/pagename.html OR
pages/pagename/index.html. The existence of a
matching directory/index will take precedence. Deep paths can be specified as
you would expect. The following path ?deep/path/to/page would
point to either the file pages/deep/path/to/page/index.html or to
pages/deep/path/to/page.html depending on your directory structure.
If a linked page is not found, an HTTP 404 error is emiited and a message is
served from the file pages/errors/404.html. If the first querystring
parameter of the URL is not a simple string like rootpath/?pagename
then an HTTP 400 error message is emitted and served from pages/errors/400.html.
Querystring parameters after the pagename parameter are perfectly
acceptable though, like this rootpath/?pagename&this=ok. If either
of these error files do not exist, a blank page will be simply by rendered
instead of an error message.
Composition
Each individual page in pages/ should be a minimal valid .html file.
The <html>, <head> and <body> tags are
omitted
as in the following example:
<!DOCTYPE html>
<title>YOUR_WINDOW/TAB_TITLE</title>
<h1>YOUR_PAGE_TITLE</h1>
<!--YOUR_CONTENT-->
Content files do not have to be Static HTML. Anywhere an .html
file can be used, a .php file could take it's place. This includes the
files in template/, as well as those in pages/. PHP files
take precedence over HTML files. Further discussion on the
usage of PHP is beyond the scope of this
document but an example of server-side rendering is included in this package.
FYI All text content before the <title> tag in your content files will be dropped.
DO NOT PLACE ANY CONTENT OTHER THAN THE DOCTYPE DECLARATION ABOVE THE TITLE TAG IN THESE FILES.
It's ok to have PHP functions, etc above the doctype as long as nothing is output before the title <title> tag.
All markup after the title tag will be injected into a <main> element with the rest of the template composed around it.
DO NOT INCLUDE <main></main> tags in your
template header/footer or in your content files, they will be added automatically.
Theming
By default the file theme.css is included in every page. Use
this to customize the general look-and-feel of your site. If you purchased a
theme, keep in mind that it will be pretty closely tied to the template scructure that
it came with. Changes you make in the header and footer files might affect how the theme looks.
Use the Theme Engine Test Page to determine if your customized
theme is covering all the necessary elements.
Aside from overall thematic changes, each content page can actually specify it's own
overriding or unique styles by including a <link rel="stylesheet">
or <style> tag after the <title> tag.
Conclusion
As you can see, this framework places very few restrictions on the structure
of your project. If you require clarification or have any comments you'd like to
share, feel free to get in touch.