anewt-developers team mailing list archive

[noreply@xxxxxxxxxxxxx]

------------------------------------------------------------
revno: 1758
committer: Wouter Bolsterlee <uws@xxxxxxxxx>
branch nick: anewt.uws
timestamp: Tue 2010-02-16 20:39:38 +0100
message:
  [page] Implement array access syntactic sugar for AnewtPage
  
  Fixes bug #514479.
  
  Added some syntactic sugar to AnewtPage that allows
  appending content to blocks easier. Yay for less typing (and
  less parentheses)! 
  
  This code:
  
    $page->append(ax_p('Some text.'));
    $page->append_to('some-block', ax_p('Some text.'));
  
  ...does exactly the same as this:
  
    $page[] = ax_p('Some text.');
    $page['some-block'][] = ax_p('Some text.');
    
  The docs have also been updated to reflect this API
  addition.
modified:
  page/page.lib.php


--
lp:anewt
https://code.launchpad.net/~uws/anewt/anewt.uws

Your team Anewt developers is subscribed to branch lp:anewt.
To unsubscribe from this branch go to https://code.launchpad.net/~uws/anewt/anewt.uws/+edit-subscription.

=== modified file 'page/page.lib.php'
--- page/page.lib.php	2009-08-02 17:06:11 +0000
+++ page/page.lib.php	2010-02-16 19:39:38 +0000
@@ -14,7 +14,7 @@
 /**
  * Class for building XHTML pages.
  */
-class AnewtPage extends AnewtContainer
+class AnewtPage extends AnewtContainer implements ArrayAccess
 {
 	/** \private Page content */
 	private $_content;
@@ -305,7 +305,7 @@
 
 		/* Initialize when needed */
 		if (!array_key_exists($name, $this->_blocks))
-			$this->_blocks[$name] = new AnewtXMLDomDocumentFragment();
+			$this->_init_block($name);
 
 		if (is_numeric_array($new_child))
 			$this->_blocks[$name]->append_children($new_child);
@@ -348,6 +348,11 @@
 		return $block;
 	}
 
+	private function _init_block($name)
+	{
+		$this->_blocks[$name] = new AnewtXMLDomDocumentFragment();
+	}
+
 	/** \} */
 
 
@@ -568,6 +573,107 @@
 	}
 
 	/** \} */
+
+	/** \{
+	 * \name Array access methods
+	 *
+	 * AnewtPage offers some syntactic sugar to reduce the amount of code
+	 * required to append content to the page. This functionality is for
+	 * convenience only and does not offer any additional features over using
+	 * AnewtPage::append() and AnewtPage::append_to().
+	 *
+	 * The array append operator on the AnewtPage instance itself (<code>$page[]
+	 * = ...</code>) can be used to append content to the default block. This
+	 * means the following two lines of code are equivalent:
+	 *
+	 * \code
+	 * $page->append(ax_p('Some text.'));
+	 * $page[] = ax_p('Some text.');
+	 * \endcode
+	 *
+	 * To append content to a specific block (other than the default block), you
+	 * may specify the block to append to by using two array operators: the
+	 * first to specify the block, and the second to append to it. Those two
+	 * lines do exactly the same:
+	 *
+	 * \code
+	 * $page->append_to('some-block', ax_p('Some text.'));
+	 * $page['some-block'][] = ax_p('Some text.');
+	 * \endcode
+	 *
+	 * Note that AnewtPage does not offer full array access: only the append
+	 * operator can be used! This mean you can only use the array operators
+	 * exactly like the examples above! In particular, never use or keep
+	 * a reference to the variable obtained from
+	 * <code>$page['some-block']</code>; you may only use it for appending
+	 * content directly using <code>$page['some-block'][] = ...</code>.
+	 */
+
+	/**
+	 * \private
+	 *
+	 * Return the named block so that one can append to it using teh ArrayAccess
+	 * interface.
+	 *
+	 * For internal use only: do not invoke this method directly.
+	 *
+	 * \param $name
+	 */
+	public function offsetGet($name)
+	{
+		if (!array_key_exists($name, $this->_blocks))
+			$this->_init_block($name);
+
+		return $this->_blocks[$name];
+	}
+
+	/**
+	 * \private
+	 *
+	 * Add content to a block using the ArrayAccess interface.
+	 *
+	 * For internal use only: do not invoke this method directly.
+	 *
+	 * \param $name
+	 *   The name of the block or null if the <code>[]</code> append operator
+	 *   was used.
+	 * \param $value
+	 *   The content to add.
+	 */
+	public function offsetSet($name, $value)
+	{
+		if (!is_null($name))
+			throw new AnewtException('Array operators on AnewtPage can only be used to append to blocks.');
+
+		if (is_null($name))
+			$this->append($value);
+	}
+
+	/**
+	 * \private
+	 *
+	 * Throws an error. (Only needed for ArrayAccess interface.)
+	 *
+	 * \param $name
+	 */
+	public function offsetExists($name)
+	{
+		throw new AnewtException('Array operators on AnewtPage can only be used to append to blocks.');
+	}
+
+	/**
+	 * \private
+	 *
+	 * Throws an error. (Only needed for ArrayAccess interface.)
+	 *
+	 * \param $name
+	 */
+	public function offsetUnset($name)
+	{
+		throw new AnewtException('Array operators on AnewtPage can only be used to append to blocks.');
+	}
+
+	/** \} */
 }
 
 ?>