Updated site pages docs.

Added ability to pass arguments to custom keywords.
Added user_list keyword.
Reject logged out front pages that don't have [[login_box]].


git-svn-id: http://code.elgg.org/elgg/trunk@5710 36083f99-b078-4883-b0ff-0f9b5a30f544

7 files changed, 119 insertions, 34 deletions

diff --git a/mod/sitepages/README.txt b/mod/sitepages/README.txt
index bc4d02007..b2c36c71e 100644
--- a/mod/sitepages/README.txt
+++ b/mod/sitepages/README.txt
@@ -80,11 +80,13 @@ CONTENTS:
 	keyword, but custom keywords provide a simple way for non-techy users to 
 	include ready-made views without the fuss of knowing what they're doing.
 
-	The below example creates the 'my_plugin_keyword' keyword that displays the
-	view at 'my_plugin/keyword_view.'
+	Custom keywords support arguments in the same format as views and entities.
+	These arguments are passed to the custom view via the $vars array.  It is
+	the responsibility of the custom view to parse these arguments.
 
-	This is exactly the same as saying [[view: my_plugin/keyword_view]] but
-	much simpler for the user.
+	The below example creates the 'my_plugin_keyword' keyword that displays the
+	view at 'my_plugin/keyword_view.'  This is exactly the same as saying 
+	[[view: my_plugin/keyword_view]] but much simpler for the user.
 
 	Example:
 		register_plugin_hook('get_keywords', 'sitepages', 'my_plugin_keywords');
@@ -98,15 +100,17 @@ CONTENTS:
 			return $value;
 		}
 
-	NB: No variables are passed to the view when using custom keywords.
-
 
 4.  HINTS AND QUIRKS
 
-	* A custom keyword is more complicated to implement, but simpler for the
-	end user.
+	* A custom keyword is slightly more complicated to implement, but is 
+	much simpler for the end user to use.
+
+	* Custom keywords can contain only alphanumeric and the underscore
+	character.
 
-	* The view and entity keywords have limited support for passing arguments, 
-	but the arguments cannot contain '=' or ','.  If you need complicated
-	arguments, it's best to create a custom keyword with a custom view.
+	* All keywords have limited support for passing arguments but the arguments
+	cannot contain '=' or ','.  If you need complicated arguments for a custom
+	keyword, it's better to split the functionality into multiple keywords and
+	views instead of requiring complicated arguments.
 	
diff --git a/mod/sitepages/actions/addfront.php b/mod/sitepages/actions/addfront.php
index fd2154cc3..f92d4614d 100644
--- a/mod/sitepages/actions/addfront.php
+++ b/mod/sitepages/actions/addfront.php
@@ -15,6 +15,12 @@ admin_gatekeeper();
 $logged_in_content = get_input('logged_in_content', '', FALSE);
 $logged_out_content = get_input('logged_out_content', '', FALSE);
 
+// do some error checking to make sure you can't lock yourself out of your front page.
+if (FALSE === strpos($logged_out_content, '[[login_box')) {
+	register_error(elgg_echo('sitepages:error:no_login'));
+	forward($_SERVER['HTTP_REFERER']);
+}
+
 $css = get_input('css', '', FALSE);
 $loggedin_user_guid = get_loggedin_userid();
 
diff --git a/mod/sitepages/languages/en.php b/mod/sitepages/languages/en.php
index 4e80c8b37..49222d7a3 100644
--- a/mod/sitepages/languages/en.php
+++ b/mod/sitepages/languages/en.php
@@ -35,6 +35,8 @@ $english = array(
 	'sitepages:addcontent' => "You can add content here via your admin tools. Look for the external pages link under admin.",
 	'item:object:front' => 'Front page items',
 
+	'sitepages:error:no_login' => 'The logged out view for the front page must contain a [[login_box]] or your users can\'t login!',
+
 	/**
 	 * Status messages
 	 */
@@ -73,6 +75,7 @@ $english = array(
 
 	'sitepages:keywords:login_box' => 'A standard login box.  Useful for the logged out content area.',
 	'sitepages:keywords:site_stats' => 'This does not exist yet.',
+	'sitepages:keywords:user_list' => "Lists users.  Supports only_with_avatars=TRUE|FALSE, list_type=newest|online|random, limit",
 );
 
 add_translation('en', $english);
\ No newline at end of file
diff --git a/mod/sitepages/sitepages_functions.php b/mod/sitepages/sitepages_functions.php
index 44cb0640d..baf8e365b 100644
--- a/mod/sitepages/sitepages_functions.php
+++ b/mod/sitepages/sitepages_functions.php
@@ -119,6 +119,8 @@ function sitepages_get_page_content($page_type) {
  * @return html
  */
 function sitepages_parse_view_match($matches) {
+	global $CONFIG;
+
 	$keyword = $matches[0];
 	$type = trim($matches[1]);
 	$params_string = trim($matches[2]);
@@ -142,6 +144,19 @@ function sitepages_parse_view_match($matches) {
 
 			break;
 
+		default:
+			// match against custom keywords with optional args
+			if (isset($CONFIG->sitepages_keywords[$type])) {
+				$keyword_info = $CONFIG->sitepages_keywords[$type];
+				$vars = sitepages_keywords_tokenize_params($params_string);
+				$content = elgg_view($keyword_info['view'], $vars);
+			}
+			break;
+	}
+
+	// if nothing matched return the original string.
+	if (!$content) {
+		$content = $matches[0];
 	}
 
 	return $content;
@@ -155,7 +170,6 @@ function sitepages_parse_view_match($matches) {
  */
 function sitepages_keywords_tokenize_params($string) {
 	$pairs = array_map('trim', explode(',', $string));
-
 	$params = array();
 
 	foreach ($pairs as $pair) {
@@ -163,7 +177,18 @@ function sitepages_keywords_tokenize_params($string) {
 
 		$name = trim($name);
 		$value = trim($value);
-		$params[$name] = $value;
+
+		// normalize BOOL values
+		if ($value === 'true') {
+			$value = TRUE;
+		} elseif ($value === 'false') {
+			$value = FALSE;
+		}
+
+		// don't check against value since a falsy/empty value is valid.
+		if ($name) {
+			$params[$name] = $value;
+		}
 	}
 
 	return $params;
@@ -211,8 +236,6 @@ function sitepages_keywords_parse_entity_params($string) {
 	return $params;
 }
 
-
-
 /**
  * Utility object to store site page information.
  */
diff --git a/mod/sitepages/start.php b/mod/sitepages/start.php
index 8450eb872..a1a9f6978 100644
--- a/mod/sitepages/start.php
+++ b/mod/sitepages/start.php
@@ -63,6 +63,7 @@ function sitepages_init() {
 
 	// grab the list of keywords and their views from plugins
 	if ($keywords = trigger_plugin_hook('get_keywords', 'sitepages', NULL, array())) {
+		ksort($keywords);
 		$CONFIG->sitepages_keywords = $keywords;
 	}
 
@@ -184,26 +185,10 @@ function sitepages_page_handler($page) {
 function sitepages_parse_view($hook, $entity_type, $return_value, $params) {
 	global $CONFIG;
 
-	// give me everything that is (string):(any thing that's not a ]) surrounded by [[ ]]s
-	$keyword_regex = '/\[\[([a-z]+):([^\]]+)\]\]/';
+	// give me everything that is (not a ]) possibly followed by a : and surrounded by [[ ]]s
+	$keyword_regex = '/\[\[([a-z0-9_]+):?([^\]]+)?\]\]/';
 
 	if (in_array($params['view'], $CONFIG->sitepages_parse_views)) {
-		$keywords = $CONFIG->sitepages_keywords;
-
-		$view_options = array(
-			'view' => $params['view']
-		);
-
-		foreach ($keywords as $keyword => $info) {
-			if (strpos($return_value, "[[$keyword]]") !== FALSE
-			&& ($content = elgg_view($info['view'], $view_options))) {
-				$return_value = str_replace("[[$keyword]]", $content, $return_value);
-			}
-		}
-
-		// parse for specialized tags:
-		//	[[entity: key=value, key=value,etc]]
-		//	[[view:viewname, vars_key=value,...]]
 		$return_value = preg_replace_callback($keyword_regex, 'sitepages_parse_view_match', $return_value);
 	}
 
@@ -226,8 +211,13 @@ function sitepages_keyword_hook($hook, $entity_type, $return_value, $params) {
 		'description' => elgg_echo('sitepages:keywords:login_box')
 	);
 
+	$return_value['user_list'] = array(
+		'view' => 'sitepages/keywords/user_list',
+		'description' => elgg_echo('sitepages:keywords:user_list')
+	);
+
 	$return_value['site_stats'] = array(
-		'view' => 'this/doesnt/exist/yet',
+		'view' => 'sitepages/keywords/site_stats',
 		'description' => elgg_echo('sitepages:keywords:site_stats')
 	);
 
diff --git a/mod/sitepages/views/default/sitepages/keywords/site_stats.php b/mod/sitepages/views/default/sitepages/keywords/site_stats.php
new file mode 100644
index 000000000..8ccb96794
--- /dev/null
+++ b/mod/sitepages/views/default/sitepages/keywords/site_stats.php
@@ -0,0 +1,12 @@
+<?php
+/**
+ * Site stats
+ *
+ * @package SitePages
+ * @license http://www.gnu.org/licenses/old-licenses/gpl-2.0.html GNU Public License version 2
+ * @author Curverider Ltd
+ * @copyright Curverider Ltd 2008-2010
+ * @link http://elgg.org/
+ */
+
+echo "N/A";
\ No newline at end of file
diff --git a/mod/sitepages/views/default/sitepages/keywords/user_list.php b/mod/sitepages/views/default/sitepages/keywords/user_list.php
new file mode 100644
index 000000000..2f2f09c49
--- /dev/null
+++ b/mod/sitepages/views/default/sitepages/keywords/user_list.php
@@ -0,0 +1,47 @@
+<?php
+/**
+ * Lists users
+ *
+ * @package SitePages
+ * @license http://www.gnu.org/licenses/old-licenses/gpl-2.0.html GNU Public License version 2
+ * @author Curverider Ltd
+ * @copyright Curverider Ltd 2008-2010
+ * @link http://elgg.org/
+ */
+
+$only_with_avatars = (isset($vars['only_with_avatars'])) ? $vars['only_with_avatars'] : TRUE;
+$list_type = (isset($vars['list_type'])) ? $vars['list_type'] : 'newest';
+$limit = (isset($vars['limit'])) ? $vars['limit'] : 10;
+
+$options = array(
+	'type' => 'user',
+	'limit' => $limit
+);
+
+if ($only_with_avatars == TRUE) {
+	$options['metadata_name_value_pairs'] = array('name' => 'icontime', 'operand' => '!=', 'value' => 0);
+}
+
+switch ($list_type) {
+	case 'newest':
+		$options['order_by'] = 'e.time_created DESC';
+		break;
+
+	case 'online':
+		// show people with a last action of < 10 minutes.
+		$last_action = time() - 10 * 60;
+		$options['joins'] = array("JOIN {$vars['config']->dbprefix}users_entity ue on ue.guid = e.guid");
+		$options['wheres'] = array("ue.last_action > $last_action");
+		break;
+
+	case 'random':
+		$options['order_by'] = 'RAND()';
+		break;
+
+	default:
+		break;
+}
+
+$users = elgg_get_entities_from_metadata($options);
+
+echo elgg_view_entity_list($users, count($users), 0, $limit, FALSE, FALSE, FALSE);
\ No newline at end of file