Comanche documentation and some cleanup of layout page (including link to doco) and a few other webpage related cleanups

7 files changed, 173 insertions, 4 deletions

diff --git a/doc/Comanche.md b/doc/Comanche.md
new file mode 100644
index 000000000..8874e839a
--- /dev/null
+++ b/doc/Comanche.md
@@ -0,0 +1,143 @@
+Comanche Page Description Language
+==================================
+
+
+Comanche is a markup language similar to bbcode with which to create elaborate and complex web pages by assembling them from a series of components - some of which are pre-built and others which can be defined on the fly. Comanche uses a Page Decription Language to create these pages.
+
+Comanche primarily chooses what content will appear in various regions of the page. The various regions have names and these names can change depending on what layout template you choose.
+
+Currently there are two layout templates, unless your site provides additional layouts (TODO list all templates)
+
+	default
+
+	The default template defines a "nav" region across the top, "aside" as a fixed width sidebar, 
+	"content" for the main content region, and "footer" for a page footer.
+
+
+	full
+
+	The full template defines the same as the default template with the exception that there is no "aside" region.
+
+
+To choose a layout template, use the 'layout' tag.
+
+	[layout]full[/layout]
+
+
+The default template will be used if no other template is specified. The template can use any names it desires for content regions. You will be using 'region' tags to decide what content to place in the respective regions.
+
+
+Two "macros" have been defined for your use.
+
+	$nav - replaced with the site navigation bar content.
+	$content - replaced with the main page content.
+
+
+By default, $nav is placed in the "nav" page region and $content is placed in the "content" region. You only need to use these macros if you wish to re-arrange where these items appear, either to change the order or to move them to other regions.
+
+
+To select a theme for your page, use the 'theme' tag.
+
+	[theme]apw[/theme]
+
+This will select the theme named "apw". By default your channel's preferred theme will be used.
+
+
+**Regions**
+
+Each region has a name, as noted above. You will specify the region of interest using a 'region' tag, which includes the name. Any content you wish placed in this region should be placed between the opening region tag and the closing tag.
+
+	[region=aside]....content goes here....[/region]
+	[region=nav]....content goes here....[/region]
+
+
+
+**Menus and Blocks**
+
+Your webpage creation tools allow you to create menus and blocks, in addition to page content. These provide a chunk of existing content to be placed in whatever regions and whatever order you specify. Each of these has a name which you define when the menu or block is created.
+
+	[menu]mymenu[/menu]
+
+This places the menu called "mymenu" at this location on the page, which must be inside a region. 
+
+	[block]contributors[/block]
+
+This places a block named "contributors" in this region.
+
+
+**Widgets**
+
+Widgets are executable apps provided by the system which you can place on your page. Some widgets take arguments which allows you to tailor the widget to your purpose. (TODO: list available widgets and arguments). The base system provides
+
+	profile - widget which duplicates the profile sidebar of your channel page. This widget takes no arguments
+	tagcloud - provides a tag cloud of categories
+		count - maximum number of category tags to list	
+
+
+
+Widgets and arguments are specified with the 'widget' and 'arg' tags.
+
+	[widget=recent_visitors][arg=count]24[/arg][/widget]
+
+This loads the "recent_visitors" widget and supplies it with the argument "count" set to "24". 
+ 
+
+**Comments**
+
+The 'comment' tag is used to delimit comments. These comments will not appear on the rendered page.
+
+	[comment]This is a comment[/comment] 
+	
+ 
+
+**Complex Example**
+
+	[comment]use an existing page template which provides a banner region plus 3 columns beneath it[/comment]
+
+	[layout]3-column-with-header[/layout]
+
+	[comment]Use the "darknight" theme[/comment]
+
+	[theme]darkknight[/theme]
+
+	[comment]Use the existing site navigation menu[/comment]
+
+	[region=nav]$nav[/region]
+
+	[region=side]
+
+		[comment]Use my chosen menu and a couple of widgets[/comment]
+
+		[menu]myfavouritemenu[/menu]
+
+		[widget=recent_visitors]
+			[arg=count]24[/arg]
+			[arg=names_only]1[/arg]
+		[/widget]
+
+		[widget=tagcloud][/widget]
+		[block]donate[/block]
+
+	[/region]
+
+
+
+	[region=middle]
+
+		[comment]Show the normal page content[/comment]
+
+		$content
+
+	[/region]
+
+
+
+	[region=right]
+
+		[comment]Show my condensed channel "wall" feed and allow interaction if the observer is allowed to interact[/comment]
+
+		[widget]channel[/widget]
+
+	[/region]
+
+
diff --git a/doc/Home.md b/doc/Home.md
index f0e731057..5f922c09d 100644
--- a/doc/Home.md
+++ b/doc/Home.md
@@ -16,6 +16,7 @@ Red Matrix Documentation and Resources
 **Technical Documentation**
 
 * [Install](help/Install)
+* [Comanche Page Descriptions](help/Comanche)
 * [Plugins](help/Plugins)
 * [Developers](help/Developers)
 * [Code](doc/html)
diff --git a/doc/Webpages.md b/doc/Webpages.md
index ddde2a401..e9943fda8 100644
--- a/doc/Webpages.md
+++ b/doc/Webpages.md
@@ -11,4 +11,4 @@ The "page link title" box allows a user to specify the "pagelinktitle" of this U
 
 Beneath the page creation box, a list of existing pages will appear with an "edit" link.  Clicking this will take you to an editor, similar to that of the post editor, where you can make changes to your webpages.
 
-If you are the admin of a site, you can speficy a channel whose webpages we will use at key points around the site.  Presently, the only place this is implemented is the home page.  If you specify the channel "admin" and then the channel called "admin" creates a webpage called "home", we will display it's content on your websites home page.  We expect this functionality to be extended to other areas in future.
\ No newline at end of file
+If you are the admin of a site, you can specify a channel whose webpages we will use at key points around the site.  Presently, the only place this is implemented is the home page.  If you specify the channel "admin" and then the channel called "admin" creates a webpage called "home", we will display it's content on your websites home page.  We expect this functionality to be extended to other areas in future.
\ No newline at end of file
diff --git a/include/comanche.php b/include/comanche.php
index 4b8a1d170..7d7e0e70c 100644
--- a/include/comanche.php
+++ b/include/comanche.php
@@ -46,6 +46,12 @@ function pdl_selector($uid,$current="") {
 
 function comanche_parser(&$a,$s) {
 
+	$cnt = preg_match_all("/\[comment\](.*?)\[\/comment\]/ism", $s, $matches, PREG_SET_ORDER);
+	if($cnt) {
+		foreach($matches as $mtch) {
+			$s = str_replace($mtch[0],'',$s);
+		}
+	}
 
 	$cnt = preg_match("/\[layout\](.*?)\[\/layout\]/ism", $s, $matches);
 	if($cnt)
diff --git a/include/conversation.php b/include/conversation.php
index 497c2fda7..831a00519 100644
--- a/include/conversation.php
+++ b/include/conversation.php
@@ -1072,6 +1072,11 @@ function status_editor($a,$x,$popup=false) {
 	$jotplugins = '';
 	$jotnets = '';
 
+
+	$preview = ((feature_enabled($x['profile_uid'],'preview')) ? t('Preview') : '');
+	if(x($x,'nopreview'))
+		$preview = '';
+
 	call_hooks('jot_tool', $jotplugins);
 	call_hooks('jot_networks', $jotnets);
 
@@ -1080,7 +1085,7 @@ function status_editor($a,$x,$popup=false) {
 		'$action' =>  $a->get_baseurl(true) . '/item',
 		'$share' => (x($x,'button') ? $x['button'] : t('Share')),
 		'$webpage' => $webpage,
-		'$placeholdpagetitle' => t('Page link title'),
+		'$placeholdpagetitle' => ((x($x,'ptlabel')) ? $x['ptlabel'] : t('Page link title')),
 		'$pagetitle' => (x($x,'pagetitle') ? $x['pagetitle'] : ''),		
 		'$upload' => t('Upload photo'),
 		'$shortupload' => t('upload photo'),
@@ -1121,7 +1126,7 @@ function status_editor($a,$x,$popup=false) {
 		'$showacl' => ((array_key_exists('showacl',$x)) ? $x['showacl'] : 'yes'),
 		'$bang' => $x['bang'],
 		'$profile_uid' => $x['profile_uid'],
-		'$preview' => ((feature_enabled($x['profile_uid'],'preview')) ? t('Preview') : ''),
+		'$preview' => $preview,
 		'$sourceapp' => t($a->sourcename),
 		'$jotplugins' => $jotplugins,
 	));
diff --git a/mod/blocks.php b/mod/blocks.php
index 170d37256..4604790c3 100644
--- a/mod/blocks.php
+++ b/mod/blocks.php
@@ -62,6 +62,7 @@ require_once ('include/conversation.php');
 			'bang' => (($group || $cid) ? '!' : ''),
 			'visitor' => 'block',
 			'mimetype' => 'choose',
+			'ptlabel' => t('Block Name'),
 			'profile_uid' => intval($owner),
 		);
 
diff --git a/mod/layouts.php b/mod/layouts.php
index cd6e61f88..b1f53d4d8 100644
--- a/mod/layouts.php
+++ b/mod/layouts.php
@@ -47,6 +47,17 @@ function layouts_content(&$a) {
             $a->set_widget('design',design_tools());
         }
 
+		$tabs = array(
+			array(
+			'label' => t('Layout Help'),
+			'url'   => 'help/Comanche',
+			'sel'   => '',
+			'title' => t('Help with this feature'),
+			'id'    => 'layout-help-tab',
+		));
+
+
+		$o .= replace_macros(get_markup_template('common_tabs.tpl'),array('$tabs' => $tabs));
 
 
 // Create a status editor (for now - we'll need a WYSIWYG eventually) to create pages
@@ -58,7 +69,9 @@ require_once ('include/conversation.php');
 			'nickname' => $a->profile['channel_address'],
 			'lockstate' => (($group || $cid || $channel['channel_allow_cid'] || $channel['channel_allow_gid'] || $channel['channel_deny_cid'] || $channel['channel_deny_gid']) ? 'lock' : 'unlock'),
 			'bang' => (($group || $cid) ? '!' : ''),
-			'visitor' => 'block',
+			'visitor' => 'none',
+			'nopreview' => 1,
+			'ptlabel' => t('Layout Name'),
 			'profile_uid' => intval($owner),
 		);