33 replies to this topic

[Ralph]

The following snippet can be seen in action on my personal development website... The URL to this example page is http://dahlgren.slyip.com/getSidebar.html and it gives a very broad example of what this snippet can do... While the snippets original conceptual design came from Ian Smith (cathode), I took the liberty of extending the functional possibilities to an almost ridiculous extent...

// Snippet: getSidebar
// Author: Ralph A. Dahlgren
// Created: 2007-03-01
// Revision: 20070305
// Origin: Based on conceptual input provided by Ian Smith (cathode) of http://www.n-vent.com
// Purpose: Queries for and displays sidebar content stored in unpublished documents.
// Usage: [ !getSidebar
//		  ?doc=sidebar
//		  &chunk=chunk_name
//		  &class=someclass
//		  &column=alias
//		  &folder=123
//		  &recursive=0 (anything else equates to true|1)
//		  &wildcard=[true|1] (anything else equates to false|0)
//		  &wrapper=[false|0] (anything else equates to true|1)
//		! ]
/*
Typical snippet call: [ !getSidebar?doc=sidebar! ]

This snippet looks for an unpublished child document titled "sidebar".
If not found, it looks above for an unpublished sibling titled "sidebar".
If not found, it looks for an unpublished doc adjacent to it's parent...
and so-on to the topmost level.

An example: Picture a website with 4 top level sections, each section has
multiple documents underneath it. Each section needs a single sidebar of
related information, examples would be "downloads" "links" or "more info."
Every document in each section needs this same sectional sidebar. To make this
work, just put [ !getSidebar?doc=downloads! ] into the template. Then, within
each section, create an unpublished document with the alias of "downloads."
This will display the proper downloads sidebar for every document in the
website. If one section doesn't need a sidebar, simply do not create one for
that section. Also, if a single document needs it's own version of a sidebar,
just give it a child document with the same title and it'll override the
parent sidebar.

Other possible uses: Using CSS and customized snippet call parameters you can
do quite a bit with this snippet. The snippet can be used in page Templates,
in Documents, or within Chunks. Use it to display multiple category specific
images. Use it to display content related information. Configure it via
snippet call paremeters to do whatever you need it to do - it's that flexible.
*/

// Define the table column to use for lookups (default="alias")
// Example: column=pagetitle would cause the pagetitle column to be used for querying
$column = isset($column) ? $column : "alias";

// Define what to look for as part of a wildcard search (default="sidebar")
// This will cause the query to look for "sidebar", "sidebar2", "somesidebar", etc...
// Example: doc=MoreInfo would find "MoreInfo1", "MoreInfo2", etc...
$doc = isset($doc) ? $doc : "sidebar";

// Define an optional folder id to use instead of the current parent folder
// Example: folder=123 would force the query to search folder id 123 for results
$folder = isset($folder) ? $folder : $etomite->documentIdentifier;

// Define the css class to assign to each sidebar item (defaults to the value of $column)
// If $column is used then each item can have its own css style
// CSS Example: .sidebar{...} .sidebar2{...} .somesidebar{...}
// Example: class=sideBar would cause .sideBar to be used for all items
$class = isset($class) ? $class : "{".$column."}";

// Determine whether or not a recursive search back to the docroot should be performed
// The only values that will stop recursion are recursive=[false|0]
$recursive = (isset($recursive) && in_array($recursive, array("false","0"))) ? false : true;

// Define optional wrapper open and close markup which will surround all sidebar markup
// The default action is to use the wrapper code below which can be modifed as needed
$wrapper = (isset($wrapper) && in_array($wrapper, array("false","0"))) ? false : true;
if($wrapper)
{
  $wrapper_open = "<div class=\"sidebar_wrapper\">";
  $wrapper_close = "</div>";
}

// Define the template markup to be used in rendering each resultset item
// Note: an alternate method would be to use $tpl = $etomite->getChunk("chunk_name");
// to retrieve markup stored in a Chunk.
if(isset($chunk))
{
  $tpl = $etomite->getChunk($chunk);
}
else
{
$tpl =
<<<END
<div class="$class">
<h1>{longtitle}</h1>
{content}
</div>
END;
}

// Define the document columns to be returned in the resultset
// Examples: "*" for all columns OR "alias,content"
$fields = "id,pagetitle,longtitle,description,alias,content";

// Look for sidebars by recursively moving back towards the doc root
while(($folder >= 0) && (count($rs) < 1))
{
  // Define the MySQL WHERE clause to be used by the query
  // If wildcard=[true|1] then we do a wildcard search, otherwise an exact search
  if($wildcard == "true" || $wildcard == "1")
  {
  $where =
	"`parent`=$folder
	  AND `$column` LIKE '%$doc%'
	  AND `published`=0"
;
  }
  else
  {
  $where =
	"`parent`=$folder
	  AND `$column`='$doc'
	  AND `published`=0"
;
  }

  // Perform the actual database query
  // Variables such as $from, $sort, and $dir have been hard-coded but could
  // be made dynamic if needed
  // See getIntTableRows() API function documentation for more information
  $rs = $etomite->getIntTableRows
  (
	$fields,
	$from="site_content",
	$where,
	$sort="alias",
	$dir="ASC",
	$limit="",
	$push=true,
	$addPrefix=true
  );
  // Retrieve the next parent if $recursive=true and $folder > 0, otherwise
  // set to -1 to stop the loop
  $folder = ($folder > 0 && $recursive) ? $etomite->parents[$folder] : -1;
}

// If results were returned process them using our template markup
// See mergeCodeVariables() API function documentation for more information
if($rs)
{
  // START::Pre-processing routines
  // Example: (Not exactly a practical example, but it gets the idea across.)
  /*
  foreach($rs as $row)
  {
	// Capitalize the first character of each word in pagetitle
	$row['pagetitle'] = ucwords(strtolower($row['pagetitle']));
	... additional per-record pre-processing code ...
  }
  */
  // END::Pre-processing routines

  $output .= ($wrapper_open != "") ? $wrapper_open : "";
  $output .= $etomite->mergeCodeVariables
  (
	$tpl,
	$rs,
	$prefix="{",
	$suffix="}",
	$oddStyle="",
	$evenStyle="",
	$tag=""
  );
  $output .= ($wrapper_close != "") ? $wrapper_close : "";
}

// START::Post-processing routine(s)
// Example:
// Remove any empty header tags
// $output = str_replace("<h1></h1>","",$output);
$output = str_replace("<h1></h1>","",$output);
// END::Post-processing routine(s)

// Return the rendered markup to caller
return $output;
// END::getSidebar

[Dean]

codeboxed

[cathode]

Dean, on Mar 7 2007, 02:29 PM, said:

codeboxed

For all who are searching for DocVars, Doc Vars or Document Variables, this new snippet takes care of that in a very easy and flexible manner. It allows for super easy multiple content areas.

[lloyd_borrett]

G'day Ralph,

I'm just starting out to use GetSidebar and I can see it's a very powerful and useful concept.

I've worked out how to get rid of the wrapper.

But this snippet also add in its own CCS div class for each sidebar item.

I can't see how I can turn off the production of that CSS div class if I don't need it.

Have I missed something, or will this require a code change.

Best Regards, Lloyd Borrett.

[lloyd_borrett]

G'day Ralph,

GetSidebar seems to rely on us being able to create multiple unplublished documents placed in the document structure which have the same alias.

But these days Etomite stops us from having multiple documents with the same alias.

So what am I doing wrong?

Best Regards, Lloyd Borrett.

Edited by lloyd_borrett, 13 March 2007 - 10:51 AM.

[lloyd_borrett]

G'day Ralph,

I think I've worked out the alias issue. Your description of the snippet is confusing, because in one part you talk about using the document title (i.e. pagetitle), but in another part you say the document alias is being used. And then the snippet code uses the alias by default.

Thus by default GetSidebar will use the document alias. Which is problematic, because Etomite will not let us have multiple documents with the same alias. So I think the default should be pagetitle, not alias.

The following version has a couple of changes I've made, including changes to the description and comments...

// Snippet: getSidebar
// Author: Ralph A. Dahlgren
// Created: 2007-03-01
// Revised: Lloyd Borrett on 2007-03-13
// Revision: 20070313
// Origin: Based on conceptual input provided by Ian Smith (cathode) of http://www.n-vent.com
// Purpose: Queries for and displays sidebar content stored in unpublished documents.
// Usage: [ !getSidebar
//		  ?doc=sidebar
//		  &chunk=chunk_name
//		  &class=someclass
//		  &column=pagetitle
//		  &folder=123
//		  &recursive=0 (anything else equates to true|1)
//		  &wildcard=[true|1] (anything else equates to false|0)
//		  &wrapper=[false|0] (anything else equates to true|1)
//		! ]
/*
Typical snippet call: [ !getSidebar?doc=sidebar! ]

This snippet looks for an unpublished child document with a page title of "sidebar".
If not found, it looks above for an unpublished sibling titled "sidebar".
If not found, it looks for an unpublished doc adjacent to it's parent...
and so-on to the topmost level.

An example: Picture a website with 4 top level sections, each section has
multiple documents underneath it. Each section needs a single sidebar of
related information, examples would be "downloads" "links" or "more info."
Every document in each section needs this same sectional sidebar. To make this
work, just put [ !getSidebar?doc=downloads! ] into the template. Then, within
each section, create an unpublished document with the page title of "downloads."
This will display the proper downloads sidebar for every document in the
website. If one section doesn't need a sidebar, simply do not create one for
that section. Also, if a single document needs it's own version of a sidebar,
just give it a child document with the same title and it'll override the
parent sidebar.

Other possible uses: Using CSS and customized snippet call parameters you can
do quite a bit with this snippet. The snippet can be used in page Templates,
in Documents, or within Chunks. Use it to display multiple category specific
images. Use it to display content related information. Configure it via
snippet call paremeters to do whatever you need it to do - it's that flexible.
*/

// Define the table column to use for lookups (default="pagetitle")
// Example: column=longtitle would cause the longtitle column to be used for querying
$column = isset($column) ? $column : "pagetitle";

// Define what to look for as part of a wildcard search (default="sidebar")
// This will cause the query to look for "sidebar", "sidebar2", "somesidebar", etc...
// Example: doc=MoreInfo would find "MoreInfo1", "MoreInfo2", etc...
$doc = isset($doc) ? $doc : "sidebar";

// Define an optional folder id to use instead of the current parent folder
// Example: folder=123 would force the query to search folder id 123 for results
$folder = isset($folder) ? $folder : $etomite->documentIdentifier;

// Define the css class to assign to each sidebar item (defaults to the value of $column)
// If $column is used then each item can have its own css style
// CSS Example: .sidebar{...} .sidebar2{...} .somesidebar{...}
// Example: class=sideBar would cause .sideBar to be used for all items
$class = isset($class) ? $class : "{".$column."}";

// Determine whether or not a recursive search back to the docroot should be performed
// The only values that will stop recursion are recursive=[false|0]
$recursive = (isset($recursive) && in_array($recursive, array("false","0"))) ? false : true;

// Define optional wrapper open and close markup which will surround all sidebar markup
// The default action is to use the wrapper code below which can be modifed as needed
$wrapper = (isset($wrapper) && in_array($wrapper, array("false","0"))) ? false : true;
if($wrapper)
{
  $wrapper_open = "<div class=\"sidebar_wrapper\">";
  $wrapper_close = "</div> <!-- end sidebar_wrapper -->";
}

// Define the template markup to be used in rendering each resultset item
// Note: an alternate method would be to use $tpl = $etomite->getChunk("chunk_name");
// to retrieve markup stored in a Chunk.
if(isset($chunk))
{
  $tpl = $etomite->getChunk($chunk);
}
else
{
$tpl =
<<<END
<div class="$class">
<h1>{longtitle}</h1>
{content}
</div> <!-- end $class -->
END;
}

// Define the document columns to be returned in the result set
// Examples: "*" for all columns OR "alias,content"
$fields = "id,pagetitle,longtitle,description,alias,content";

// Look for sidebars by recursively moving back towards the doc root
while(($folder >= 0) && (count($rs) < 1))
{
  // Define the MySQL WHERE clause to be used by the query
  // If wildcard=[true|1] then we do a wildcard search, otherwise an exact search
  if($wildcard == "true" || $wildcard == "1")
  {
  $where =
	"`parent`=$folder
	  AND `$column` LIKE '%$doc%'
	  AND `published`=0"
 ;
  }
  else
  {
  $where =
	"`parent`=$folder
	  AND `$column`='$doc'
	  AND `published`=0"
 ;
  }
  // Perform the actual database query
  // Variables such as $from, $sort, and $dir have been hard-coded but could
  // be made dynamic if needed
  // See getIntTableRows() API function documentation for more information
  $rs = $etomite->getIntTableRows
  (
	$fields,
	$from="site_content",
	$where,
	$sort="alias",
	$dir="ASC",
	$limit="",
	$push=true,
	$addPrefix=true
  );
  // Retrieve the next parent if $recursive=true and $folder > 0, otherwise
  // set to -1 to stop the loop
  $folder = ($folder > 0 && $recursive) ? $etomite->parents[$folder] : -1;
}

// If results were returned process them using our template markup
// See mergeCodeVariables() API function documentation for more information
if($rs)
{
  // START::Pre-processing routines
  // Example: (Not exactly a practical example, but it gets the idea across.)
  /*
  foreach($rs as $row)
  {
	// Capitalize the first character of each word in pagetitle
	$row['pagetitle'] = ucwords(strtolower($row['pagetitle']));
	... additional per-record pre-processing code ...
  }
  */
  // END::Pre-processing routines
  $output .= ($wrapper_open != "") ? $wrapper_open : "";
  $output .= $etomite->mergeCodeVariables
  (
	$tpl,
	$rs,
	$prefix="{",
	$suffix="}",
	$oddStyle="",
	$evenStyle="",
	$tag=""
  );
  $output .= ($wrapper_close != "") ? $wrapper_close : "";
}

// START::Post-processing routine(s)
// Example:
// Remove any empty header tags
// $output = str_replace("<h1></h1>","",$output);
$output = str_replace("<h1></h1>","",$output);
// END::Post-processing routine(s)

// Return the rendered markup to caller
return $output;
// END::getSidebar

I haven't figured out how one should go about making it optional as to whether a class is added or not.

Best Regards, Lloyd Borrett.

Edited by Dean, 13 March 2007 - 12:30 PM.
codeboxed

[cathode]

Lloyd,
You're right. I had to make the same change- it makes more sense for the title to be the default. The problem was that I wrote the parts referring to the title and Ralph wrote the other parts...

[cathode]

lloyd_borrett, on Mar 13 2007, 03:54 AM, said:

G'day Ralph,

I'm just starting out to use GetSidebar and I can see it's a very powerful and useful concept.

I've worked out how to get rid of the wrapper.

But this snippet also add in its own CCS div class for each sidebar item.

I can't see how I can turn off the production of that CSS div class if I don't need it.

Have I missed something, or will this require a code change.

Best Regards, Lloyd Borrett.

I wonder if you could just comment out this line: $class = isset($class) ? $class : "{".$column."}";

[cathode]

cathode, on Mar 13 2007, 08:23 AM, said:

I wonder if you could just comment out this line: $class = isset($class) ? $class : "{".$column."}";

I tried it, I guess that won't work.

Another thing that confuses me:

take this line: $recursive = (isset($recursive) && in_array($recursive, array("false","0"))) ? false : true;
Which part do I change to make this true? do I change all of the falses to true, and all of the 0's to 1's?

[mikef]

cathode, on Mar 13 2007, 12:33 PM, said:

take this line: $recursive = (isset($recursive) && in_array($recursive, array("false","0"))) ? false : true;
Which part do I change to make this true? do I change all of the falses to true, and all of the 0's to 1's?

replace with

$recursive=true;

Not having looked at the code I've no idea if doing that makes sense though.

[Ralph]

cathode, on Mar 13 2007, 08:33 AM, said:

I tried it, I guess that won't work.

Another thing that confuses me:

take this line: $recursive = (isset($recursive) && in_array($recursive, array("false","0"))) ? false : true;
Which part do I change to make this true? do I change all of the falses to true, and all of the 0's to 1's?

Yes, changing the booleans to opposites will reverse the effect of the logic in the line above...

[cathode]

Ralph, on Mar 13 2007, 10:22 AM, said:

Yes, changing the booleans to opposites will reverse the effect of the logic in the line above...

I'd much prefer a simple switch, if what you're describing is the following:

true= $recursive = (isset($recursive) && in_array($recursive, array("true","1"))) ? true: false;
false= $recursive = (isset($recursive) && in_array($recursive, array("false","0"))) ? false : true;

I mean, why not make a single 1|0 instead of changing the line in four different places?

Edited by cathode, 13 March 2007 - 03:08 PM.

[Ralph]

cathode, on Mar 13 2007, 10:54 AM, said:

I'd much prefer a simple switch, if what you're describing is the following:

true= $recursive = (isset($recursive) && in_array($recursive, array("true","1"))) ? true: false;
false= $recursive = (isset($recursive) && in_array($recursive, array("false","0"))) ? false : true;

I mean, why not make a single 1|0 instead of changing the line in four different places?

I guess it depends on whether you want recursion by default or not... I simply use a snippet call parameter to toggle from the default... You just need to decide on what value you want the default to be, true or false... Every user might want different defaults and this is how they would be made, just as other settings can have their defaults modified...

[cathode]

Ralph, on Mar 13 2007, 11:20 AM, said:

I guess it depends on whether you want recursion by default or not... I simply use a snippet call parameter to toggle from the default... You just need to decide on what value you want the default to be, true or false... Every user might want different defaults and this is how they would be made, just as other settings can have their defaults modified...

I guess that makes sense, but I just don't get the complexity of the switch itself. It ma be a result of my lack of programming knowledge.

Instead of this: $recursive = (isset($recursive) && in_array($recursive, array("false","0"))) ? false : true;
why not just have this: $recursive = true;

[Ralph]

cathode, on Mar 13 2007, 11:28 AM, said:

I guess that makes sense, but I just don't get the complexity of the switch itself. It ma be a result of my lack of programming knowledge.

Instead of this: $recursive = (isset($recursive) && in_array($recursive, array("false","0"))) ? false : true;
why not just have this: $recursive = true;

That, as a user modification, would work... It would, however, negate the ability to make snippet call changes...

[lloyd_borrett]

G'day Ralph,

Just how can I stop GetSidebar from outputing the extra div? I'm not sure how the code needs to be achieved to do this.

Best Regards, Lloyd Borrett.

[Ralph]

lloyd_borrett, on Mar 13 2007, 05:58 PM, said:

G'day Ralph,

Just how can I stop GetSidebar from outputing the extra div? I'm not sure how the code needs to be achieved to do this.

Best Regards, Lloyd Borrett.

Try adding wrapper=0 as a snippet call parameter... You could also add $wrapper = false; at the top of the snippet to permanently disable the wrapper feature...

[lloyd_borrett]

Sorry Ralph,

wrapper = 0 only controls the output of the class = sidebar_wrapper div.

I want to also control the output of the class = someclass div. By default, I'm going to always get a class = column div.

There seems to be no way to stop this div being generated. Even if I pass a null argument for the class, I'm still going to get the div open

<div class="">

and the div close statements being included in the output.

I'd prefer to have it that the default was that no class = someclass div is generated, and that if I specify a class value as an argument to the snippet, then the class = someclass div is generated. Failing that, I'd just like some way to say that I don't want the class = someclass div being generated.

I guess it means manipulating the section of the code...

$tpl =
<<<END
<div class="$class">
<h1>{longtitle}</h1>
{content}
</div> <!-- end $class -->
END;

in an appropriate fashion.

Best Regards, Lloyd Borrett.

Edited by lloyd_borrett, 14 March 2007 - 05:11 AM.

[Ralph]

You're headed in the right direction, Lloyd... You won't read anywhere in the code or in my initial release notes that the snippet won't need to be customized... Most of the code that is in place is there merely for the purpose of spawning ingenuity into the minds of developers... This concept falls in line with my thinking that it's better to give someone ideas and direction than to simply doing the job for them... Think of getSidebar as a learning tool - not as a be all, end all, turn-key solution... There's no need in posting "proposed changes" as anyone can do whatever they want with the code, which was my original intent in releasing it to the public... Grab it, tear it apart, rebuild it to suit, and use it... If you have an imagination then the creative juices should start flowing somewhere along the way...

[lloyd_borrett]

G'day,

Attached is my latest version of getSidebar.

I know Ralph, being the true developer spirit he is, throws something like getSidebar out there and expects us all to put on our coding hats and adapt it to what we want it to be. (Which is great, because then we great great new stuff like this.) However, I also know that quite a few people prefer a more buttoned down version, because they don't have the skills to make coding changes, but still want to be able to use the power of such a snippet.

So I've had a go at buttoning getSidebar down a bit more. Hopefully I've created a default version that's a touch easier to start utilising.

In this version you can turn off the generation of the div class. &class=false|0 will do that. Anything else passed as the class argument is used as the div class. If the class argument isn't given, then class = column.

I've changed the &wrapper argument to work in a similar fashion. &wrapper=false|0 will cause the wrapper not to be output. If you specify anything else, i.e. &wrapper=somewrapper then somewarapper is used as the wrapper div class. (This is additional functionality.) If nothing is specified the wrapper=sidebar_wrapper, which was the default action of Ralph's version.

(Sorry if the above description is a bit confusing. In getSidebar there are actually two div wrappers that are put around the code output. The outer one was always class=sidebar_wrapper but it could be turned off using the &wrapper argument. Now you can also specify a different class name for this wrapper using the &wrapper argument. The inner one was controlled by the &class argument and defaulted to the value of the &column argument. Now there is a way to turn off this inner wrapper.)

In this version, the default for &column is the pagetitle instead of the alias. You can have multiple pagetitles all the same which I think is an easier way to use the snippet. You have to use the wildcard feature to use alias for the column value, because Etomite won't let you have two documents with the same alias.

I've also added in a check for the wildcard argument being present.

When I open a div, I also like to have a XHTML comment with the name of the class or id of the div where I close it. So I've added that into the markup as well.

I can't say I've extensively tested it, but it seems to be working okay on the web site where I'm already using getSidebar.

So there you have it. A few hacks from me. You can choose to use it as is, hack away at it to your hearts content, or ignore it.

Best Regards, Lloyd Borrett.

Attached Files

•  getSidebar_20070316.zip   2.94K   44 downloads

Edited by lloyd_borrett, 16 March 2007 - 10:37 PM.