trivial 0.0.5 → 0.0.6

data/CHANGELOG

@@ -0,0 +1 @@
+v0.0.6. Added better asset tags, cachebusters, code cleanup, better documentation, upgrade functionality.

data/Manifest

@@ -1,10 +1,43 @@
+CHANGELOG
 Manifest
 Rakefile
 bin/trivialize
+config/trivial.inc
+content/dynamic.inc
 content/index.html
 dist/htaccess.dist
 lib/trivial.php
 readme.md
 styles/application.css
-trivial.gemspec
+styles/blueprint/LICENSE
+styles/blueprint/ie.css
+styles/blueprint/plugins/buttons/icons/cross.png
+styles/blueprint/plugins/buttons/icons/key.png
+styles/blueprint/plugins/buttons/icons/tick.png
+styles/blueprint/plugins/buttons/readme.txt
+styles/blueprint/plugins/buttons/screen.css
+styles/blueprint/plugins/fancy-type/readme.txt
+styles/blueprint/plugins/fancy-type/screen.css
+styles/blueprint/plugins/link-icons/icons/doc.png
+styles/blueprint/plugins/link-icons/icons/email.png
+styles/blueprint/plugins/link-icons/icons/external.png
+styles/blueprint/plugins/link-icons/icons/feed.png
+styles/blueprint/plugins/link-icons/icons/im.png
+styles/blueprint/plugins/link-icons/icons/pdf.png
+styles/blueprint/plugins/link-icons/icons/visited.png
+styles/blueprint/plugins/link-icons/icons/xls.png
+styles/blueprint/plugins/link-icons/readme.txt
+styles/blueprint/plugins/link-icons/screen.css
+styles/blueprint/plugins/rtl/readme.txt
+styles/blueprint/plugins/rtl/screen.css
+styles/blueprint/print.css
+styles/blueprint/screen.css
+styles/blueprint/src/forms.css
+styles/blueprint/src/grid.css
+styles/blueprint/src/grid.png
+styles/blueprint/src/ie.css
+styles/blueprint/src/print.css
+styles/blueprint/src/reset.css
+styles/blueprint/src/typography.css
+upgrade-notes/0.0.6.txt
 views/application.inc

data/Rakefile

@@ -1,8 +1,9 @@
 require 'rubygems'
 require 'rake'
 require 'echoe'
+require 'fileutils'
 
-Echoe.new('trivial', '0.0.5') do |p|
+Echoe.new('trivial') do |p|
 	p.summary = "Ultra-lightweight website framework for PHP"
 	p.description = <<-EOT
 		For those who are using PHP to build their sites and want a very simple framework
@@ -16,3 +17,17 @@ Echoe.new('trivial', '0.0.5') do |p|
 	p.email = "john@coswelproductions.com"
 	p.url = "http://github.com/johnbintz/trivial"
 end
+
+namespace :blueprint do
+  desc "Include the latest Blueprint CSS files"
+  task :download do
+    FileUtils.rm_r 'blueprint' if File.directory? 'blueprint'
+    FileUtils.mkdir 'blueprint'
+    Dir.chdir 'blueprint'
+    system 'git clone git://github.com/joshuaclayton/blueprint-css.git'
+    FileUtils.cp_r File.join('blueprint-css', 'blueprint'), File.join('..', 'styles')
+    FileUtils.cp File.join('blueprint-css', 'LICENSE'), File.join('..', 'styles', 'blueprint')
+    Dir.chdir '..'
+    FileUtils.rm_r 'blueprint'
+  end
+end

data/bin/trivialize

@@ -6,24 +6,87 @@ if !ARGV[0]
 	exit 1
 end
 
-puts "Trivializing #{ARGV[0]}"
-FileUtils.mkdir ARGV[0] if (!File.directory? ARGV[0])
-%w{content actions views scripts styles lib}.each do |dir|
-	FileUtils.mkdir File.join(ARGV[0], dir) if (!File.directory? File.join(ARGV[0], dir))
-end
+class Installer
+	def initialize(dest_dir)
+		@dest_dir = dest_dir
+	end
+
+	def self.go(dest_dir, &block)
+		installer = Installer.new(dest_dir)
+		installer.instance_eval &block
+	end
+
+	def mk_mydir
+		FileUtils.mkdir @dest_dir if (!File.directory? @dest_dir)
+	end
+
+	def mkdir(dirs)
+		dirs.each do |dir|
+			FileUtils.mkdir File.join(@dest_dir, dir) if (!File.directory? File.join(@dest_dir, dir))
+		end
+	end
+
+	def dest_path(*dest)
+		File.join(@dest_dir, *dest)
+	end
+
+	def paths_to_a(*paths)
+		paths.collect do |path|
+			if path.kind_of? String
+				path = path.split('/')
+			end
+      path
+		end
+	end
 
-[
-	[ [File.dirname(__FILE__), '..', 'lib', 'trivial.php'], [ARGV[0], 'lib', 'trivial.php'] ],
-	[ [File.dirname(__FILE__), '..', 'dist', 'htaccess.dist'], [ARGV[0], '.htaccess'] ],
-	[ [File.dirname(__FILE__), '..', 'views', 'application.inc'], [ARGV[0], 'views', 'application.inc'] ],
-	[ [File.dirname(__FILE__), '..', 'content', 'index.html'], [ARGV[0], 'content', 'index.html'] ],
-	[ [File.dirname(__FILE__), '..', 'styles', 'application.css'], [ARGV[0], 'styles', 'application.css'] ]
-].each do |src, dest|
-	if !File.exists? File.join(*dest)
-		FileUtils.cp(File.join(*src), File.join(*dest))
-	else
-		puts "Won't overwrite existing #{File.join(*dest)}!"
+	def overwrite(source, dest = nil)
+		dest = source if (dest == nil)
+    source, dest = paths_to_a source, dest
+    source_path = File.join(File.dirname(__FILE__), '..', *source)
+    if File.directory? source_path
+      FileUtils.cp_r source_path, dest_path(*dest)
+    else
+		  FileUtils.cp source_path, dest_path(*dest)
+    end
 	end
+
+	def copy(source, dest = nil)
+		dest = source if (dest == nil)
+    source, dest = paths_to_a source, dest
+		if !File.exists? dest_path(*dest)
+			overwrite(source, dest)
+		else
+			puts "Won't overwrite existing #{dest_path(*dest)}!"
+		end
+  end
 end
 
-puts "Done! Make sure you can use .htaccess files in your Webserver setup."
+if ARGV[0] == '--upgrade'
+	puts "Upgrading to latest version..."
+
+	Installer.go(Dir.pwd) do
+    mkdir %w{config}
+
+		overwrite 'lib/trivial.php'
+    copy 'config/trivial.inc'
+	end
+
+  puts "Done!"
+else
+	puts "Trivializing #{ARGV[0]}"
+
+	Installer.go(ARGV[0]) do
+    mk_mydir
+    mkdir %w{content actions views scripts styles lib config}
+
+		copy 'lib/trivial.php'
+    copy 'config/trivial.inc'
+    copy 'dist/htaccess.dist', '.htaccess'
+    copy 'views/application.inc'
+    copy 'content/index.html'
+    copy 'styles/application.css'
+    overwrite 'styles/blueprint'
+	end
+
+	puts "Done! Make sure you can use .htaccess files in your Webserver setup."
+end

data/config/trivial.inc

@@ -0,0 +1,3 @@
+<?php
+
+$trivial_env = "development";

data/content/dynamic.inc

@@ -0,0 +1 @@
+<?php echo "hello world!" ?>

data/lib/trivial.php

@@ -1,15 +1,41 @@
 <?php
 
-// If you're using a different global default layout name, change it here
-$layout = 'application';
+define('TRIVIAL_VERSION', '0.0.6');
+
+// PUT SITE CONFIGURATION IN config/trivial.inc
 
 if (!isset($_SERVER['REDIRECT_URL'])) {
 	header('HTTP/1.1 403 Forbidden');
 	exit(1);
 }
 
-// END OF USER-CONFIGURABLE SETTINGS
+$root_dir = realpath(dirname(__FILE__) . '/../');
+
+// All of these should be set within config/trivial.inc!
+
+// The default layout.
+$layout = 'application';
+
+// Additional scripts and stylesheets can be loaded in this way. Blueprint does not get loaded this way.
+$global_head = array('scripts' => array(), 'styles' => array());
+
+// If the environment is anything but production, errors will be rendered in the page.
+$trivial_env = 'development';
+
+if (($config = fe_check('config/trivial.inc')) !== false) {
+	include($config);
+}
+
+$trim = str_replace(realpath($_SERVER['DOCUMENT_ROOT']), '', realpath($root_dir));
 
+$requested = preg_replace('#/$#', '/index.html', $_SERVER['REDIRECT_URL']);
+$requested = preg_replace("#${trim}/(.*)\.[^\.]+\$#", '\1', $requested);
+
+/**
+ * Check the root path for the requested file.
+ * @param string $path The path to look for.
+ * @return string The path to the file on the filesystem, or false if not found.
+ */
 function fe_check($path) {
 	global $root_dir;
 	if (file_exists($full_path = ($root_dir . '/' . $path))) {
@@ -19,6 +45,13 @@ function fe_check($path) {
 	}
 }
 
+/**
+ * Load a partial file.
+ * Partials live in the views directory and are prefixed with an underscore (ex: section/_a_partial.inc).
+ * @param string $name The name of the partial without the leading underscore (ex: section/a_partial).
+ * @param array $local A hash of variables to include into the local scope of the partial.
+ * @return string The partial's result.
+ */
 function partial($name, $local = array()) {
 	$name = preg_replace('#/([^/]+)$', '/_\1', $name);
 	if (($path = fe_check('views/' . $name . '.inc')) !== false) {
@@ -27,62 +60,155 @@ function partial($name, $local = array()) {
 		include($path);
 		return ob_get_clean();
 	} else {
-		trigger_error("No partial named ${name} found!");
+		render_error("No partial named ${name} found!");
 	}
 }
 
-$root_dir = realpath(dirname(__FILE__) . '/../');
-
-$trim = str_replace(realpath($_SERVER['DOCUMENT_ROOT']), '', realpath($root_dir));
-
-$requested = preg_replace('#/$#', '/index.html', $_SERVER['REDIRECT_URL']);
-$requested = preg_replace("#${trim}/(.*)\.[^\.]+\$#", '\1', $requested);
+/**
+ * Handle a rendering error.
+ * If the environment is 'production', the error is only logged. If it's anything else, it's printed
+ * on the screen. Regardless, an HTTP 500 error is returned and processing stops.
+ * @param string $error The error message to display.
+ */
+function render_error($error) {
+	global $trivial_env;
+	if ($trivial_env == 'production') {
+		error_log($error);
+	} else {
+		echo "<div id='trivial-error'>${error}</div>";
+	}
+	header('HTTP/1.1 500 Internal Server Error');
+	exit(1);
+}
 
+/**
+ * Render style link tags.
+ */
 function styles() {
-	return head_component(func_get_args(), 'styles/%s.css',	'<link rel="stylesheet" href="styles/%s.css" type="text/css" />');
+	return head_component('style', func_get_args());
 }
 
+/**
+ * Render script tags.
+ */
 function scripts() {
-	return head_component(func_get_args(), 'scripts/%s.js',	'<script type="text/javascript" src="scripts/%s.js"></script>');
+	return head_component('script', func_get_args());
+}
+
+/**
+ * Render a style tag.
+ */
+function style($name, $additional = '') {
+	return asset($name, 'styles/%s.css', '<link rel="stylesheet" href="styles/%s.css%s" type="text/css" %s/>', true, $additional);
+}
+
+/**
+ * Render a script tag.
+ */
+function script($name) {
+	return asset($name, 'scripts/%s.js', '<script type="text/javascript" src="scripts/%s.js%s"></script>');
+}
+
+/**
+ * Render an asset tag, busting the cache if necessary.
+ */
+function asset($name, $search, $format, $bust_cache = true, $additional = '') {
+	if (($file = fe_check(sprintf($search, $name))) !== false) {
+		return sprintf($format, $name, $bust_cache ? cachebuster($file) : '', $additional);
+	}
+	return '';
+}
+
+/**
+ * Get a cachebuster string for a file.
+ */
+function cachebuster($file) {
+	if (file_exists($file)) {
+		return '?' . filemtime($file);
+	} else {
+		return '';
+	}
 }
 
-function head_component($additional, $search, $format) {
-	global $requested;
+/**
+ * Render head compoments.
+ * @param string $what The type of component to render. $global_head is searched for a matching key and values for that key are merged into the list of styles.
+ * @param array $additional An array of additional components to display.
+ * @param string $search The search pattern to use for each component, run through sprintf() with the first %s being replaced with the component name.
+ * @param string $format The output format of the HTML tag to bring in the content.
+ * @return string The HTML for all found components.
+ */
+function head_component($what, $additional = array()) {
+	global $requested, $global_head;
 
 	$output = array();
-	foreach (array_merge(array('application', $requested), $additional) as $file) {
-		if (fe_check(sprintf($search, $file)) !== false) {
-			$output[] = sprintf($format, $file);
-		}
+
+	$components = $additional;
+
+	if (isset($global_head[$what]) && is_array($global_head[$what])) {
+		$components = array_merge($components, $global_head[$what]);
 	}
+
+	$components = array_merge($components, array('application', $requested));
+
+	foreach ($components as $name) { $output[] = call_user_func($what, $name); }
 	return implode("\n", $output);
 }
 
+/**
+ * Get the code to embed the Blueprint CSS framework.
+ * You should be starting with Blueprint and working your way from there, if only for the CSS reset & IE fixes alone.
+ * @return string The HTML for Blueprint.
+ */
+function blueprint() {
+  $output = array();
+  $output[] = style('blueprint/screen', 'media="screen, projection"');
+  $output[] = style('blueprint/print', 'media="print"');
+  $output[] = '<!--[if lte IE 8]>';
+  $output[] = style('blueprint/ie', 'media="screen, projection"');
+  $output[] = '<![endif]-->';
+  return implode('', $output);
+}
+
+// Search for files in the content directory, starting with .inc files (which will be include()d), then .html files (which will be file_get_content()sed)
 $content = null;
-if (($content_file = fe_check('content/' . $requested . '.html')) !== false) {
-	$content = file_get_contents($content_file);
+if (($content_file = fe_check('content/' . $requested . '.inc')) !== false) {
+	ob_start();
+	include($content_file);
+	$content = ob_get_clean();
+} else {
+	if (($content_file = fe_check('content/' . $requested . '.html')) !== false) {
+		$content = file_get_contents($content_file);
+	}
 }
 
+// Look for an action for the request. If it's found, execute it. Remember, $content contains the result of the above operation, if something was found.
 foreach (array('application', $requested) as $action) {
 	if (($action_file = fe_check('actions/' . $action . '.inc')) !== false) {
 		include($action_file);
 	}
 }
 
+// Look for a view with the same name as the request. If it's found, include() it, wrapping the include() in an output buffer block.
 if (($view_file = fe_check('views/' . $requested . '.inc')) !== false) {
 	ob_start();
 	include($view_file);
 	$content = ob_get_clean();
 }
 
+// We should have content by this point. If not, raise an error.
 if (is_null($content)) {
-	trigger_error("No content generated for ${requested}! Did you create a content, action, or view file for this request?");
+	render_error("No content generated for ${requested}! Did you create a content, action, or view file for this request?");
 }
 
+// We should have a layout, too. If not, raise an error.
 if (($layout_file = fe_check('views/' . $layout . '.inc')) !== false) {
 	ob_start();
 	include($layout_file);
 	$content = ob_get_clean();
+} else {
+	render_error("Layout not found: ${layout}");
 }
 
+// We're done!
 echo $content;

data/readme.md

@@ -16,22 +16,96 @@ A new binary is created, `trivialize`.
 
 A directory called `my-new-site` will be created with the site structure in place. An example `content/index.html` and `views/application.inc` will also be installed.
 
+## Upgrading an existing site
+
+Backup your existing site folder, `cd` to the site folder and type:
+
+`trivialize --upgrade`
+
+The following files will be overwritten:
+
+* `lib/trivial.php`
+* `styles/blueprint`
+
+And if they don't exist, the following files will be created:
+
+* `config/trivial.inc`
+
 ## The request process
 
 When a request comes in to that directory for a file that doesn't exist, trivial
 does the following (for the examples, the request was for `about_us/contact.html` and the default `$layout` value is `"application"`):
 
-* The `content` folder is checked for a `.html` file that matches the path (`content/about_us/contact.html`). If it exists, the contents of the file are pulled into the global `$content` variable.
+* The `content` folder is checked for an `.html` or `.inc` file that matches the path (`content/about_us/contact.html`).
+  * If a `.html` file exists, the contents of the file are pulled into the global `$content` variable.
+  * If a `.inc` file exists, the file is include()d and the output is placed into the global `$content` variable.
 * The `actions` folder is checked for two files:
 	* `actions/application.inc`
 	* `actions/about_us/contact.inc`
-	Each found file is included into the program, potentially modifying `$content` or `$layout`.
+	Each found file is included into the program in that order, potentially modifying `$content` or `$layout`.
 * The `views` folder is checked for two files:
 	* `views/about_us/contact.inc`
 	* `views/application.inc`
 	Each found file is included into the program, including `$content` where specified and outputting back into `$content`.
+	A layout *must exist* or an error will occur.
 * The value of `$content` is output to the visitor.
 
 ## Styles and scripts
 
-Styles and scripts can be searched for in a structured way. The included `views/application.inc` gives an example as to how this works.
+By default, the provided `views/application.inc` file has three functions for including stylesheets and scripts:
+
+    <head>
+      <?php echo blueprint() ?>
+      <?php echo scripts() ?>
+      <?php echo styles() ?>
+    </head>
+
+### Blueprint
+
+The latest [Blueprint CSS Framework](http://blueprintcss.org/) comes with Trivial. It's included into the defaut application.inc layout
+with the `blueprint()` function. Blueprint's licence can be found in the `styles/blueprint` directory.
+
+### Other Styles and Scripts
+
+The `scripts()` and `styles()` functions, by default, only search for files named `application.ext` and `name/of/request.ext`.
+For the request `contact/about_us.html`, the following JavaScript and CSS files will be searched for, in this order:
+
+* `scripts/application.js`
+* `scripts/contact/about_us.js`
+* `styles/application.css`
+* `styles/contact/about_us.css`
+
+You can incude other scripts and stylesheets in several ways:
+
+#### Globally, before application- and page-specific includes
+
+Inside of `config/trivial.inc`, add the following variable definition:
+
+`$global_head = array('scripts' => array(), 'styles' => array());`
+
+In the `scripts` and `styles` arrays, add the names of the other files to include, not including the extension:
+
+`$global_head = array('scripts' => array('jquery-1.4.2.min'), 'styles' => array('client'));`
+
+These scripts are loaded before the ones listed above, so the new search path becomes:
+
+* `scripts/jquery-1.4.2.min.js`
+* `scripts/application.js`
+* `scripts/contact/about_us.js`
+* `styles/client.css`
+* `styles/application.css`
+* `styles/contact/about_us.css`
+
+#### Locally, via a view, before application- and page-specific includes
+
+In your view, modify `$global_head` as you would above.
+
+#### Within the layout, without adding new script() or style() tags
+
+Adding additional parameters to the `scripts()` or `styles()` tag works the same as adding items to the `$global_head`:
+
+`<?php echo scripts('jquery-1.4.2.min') ?>`
+`<?php echo styles('client') ?>`
+
+Scripts/styles defined in the tag itself are loaded before `$global_head`.
+