From: x2003bruneau <x2003bruneau@9869982d-c50d-0410-be91-f2a2ec7c7c7b>
Date: Wed, 10 Jan 2007 14:46:03 +0000 (+0000)
Subject: Add documentation in page.inc.php
X-Git-Url: http://git.polytechnique.org/?a=commitdiff_plain;h=ded3974d74b5eacf42932990eed9ba79ef5d2240;p=banana.git

Add documentation in page.inc.php
Move subscription page to "action=subscribe" instead of "subscribe=1"
Some fixes


git-svn-id: svn+ssh://murphy/home/svn/banana/trunk@149 9869982d-c50d-0410-be91-f2a2ec7c7c7b
---

diff --git a/banana/banana.inc.php.in b/banana/banana.inc.php.in
index d3e983e..c564a0c 100644
--- a/banana/banana.inc.php.in
+++ b/banana/banana.inc.php.in
@@ -145,7 +145,7 @@ class Banana
 
         // Look for the action to execute
         if (is_null(Banana::$group)) {
-            if (isset($this->params['subscribe'])) {
+            if (isset($this->params['action']) && $this->params['action'] == 'subscribe') {
                 Banana::$action = Banana::ACTION_BOX_SUBS;
             } else {
                 Banana::$action = Banana::ACTION_BOX_LIST;
@@ -173,27 +173,6 @@ class Banana
         }
     }
 
-    /** Register an action to show on banana page
-     * @param action_code HTML code of the action
-     * @param pages ARRAY pages where to show the action (null == every pages)
-     * @return true if success
-     */
-    public function registerAction($action_code, array $pages = null)
-    {
-        return Banana::$page->registerAction($action_code, $pages);
-    }
-
-    /** Register a new page
-     * @param name Name of the page
-     * @param text Text for the tab of the page
-     * @param template Template path for the page if null, the page is not handled by banana
-     * @return true if success
-     */
-    public function registerPage($name, $text, $template = null)
-    {
-        return Banana::$page->registerPage($name, $text, $template);
-    }
-
     /** Run Banana
      * This function need user profile to be initialised
      */
diff --git a/banana/page.inc.php b/banana/page.inc.php
index b897146..92d4509 100644
--- a/banana/page.inc.php
+++ b/banana/page.inc.php
@@ -28,34 +28,58 @@ class BananaPage extends Smarty
     
     }
 
+    /** Add an error message
+     * @param message STRING html code of the error to display
+     */
     public function trig($message)
     {
         $this->error[] = $message;
     }
 
+    /** Kill the current page (generate an error message and skip page generation)
+     * @param message STRING html code of the error message to display
+     @ @return XHTML code of the page
+     */
     public function kill($message)
     {
         $this->trig($message);
+        $this->assign('killed', true);
         return $this->run();
     }
 
+    /** Set the current page
+     * @param page STRING page name
+     */
     public function setPage($page)
     {
         $this->page = $page;
     }
 
+    /** Register an action to show on banana page
+     * @param action_code HTML code of the action
+     * @param pages ARRAY pages where to show the action (null == every pages)
+     * @return true if success
+     */ 
     public function registerAction($action_code, array $pages = null)
     {
         $this->actions[] = array('text' => $action_code, 'pages' => $pages);
         return true;
     }
 
+    /** Register a new page
+     * @param name Name of the page
+     * @param text Text for the tab of the page
+     * @param template Template path for the page if null, the page is not handled by banana
+     * @return true if success
+     */
     public function registerPage($name, $text, $template = null)
     {
         $this->pages[$name] = array('text' => $text, 'template' => $template);
         return true;
     }
-
+    
+    /** Generate XHTML code
+     */
     public function run()
     {
         $this->registerPage('subscribe', _b_('Abonnements'), null);
@@ -107,7 +131,22 @@ class BananaPage extends Smarty
         return $text;
     }
 
-    public function makeUrl($params, &$smarty = null)
+    /** Build a URL in Banana
+     * @param params ARRAY location datas
+     * @param smarty OBJECT Smarty instance associated (null if none)
+     * @return URL of the page associated with the given parameters
+     * 
+     * Usual parameters are :
+     * - group : the box name
+     * - artid : the current message id (index of message-id)
+     * - part  : part id to show (may be a content-id, xface or a mime-type for text)
+     * - first : first linear-index to show in spool view
+     * - action: like subscribe, cancel, new
+     * - all others params are allowed, but not parsed by the base implementation of banana
+     *
+     * smarty funciton : {url param1=... param2=...}
+     */
+    public function makeUrl(array $params, &$smarty = null)
     {
         if (function_exists('hook_makeLink')
                 && $res = hook_makeLink($params)) {
@@ -131,7 +170,21 @@ class BananaPage extends Smarty
         return $proto . $host . $file . $get;
     }
 
-    public function makeLink($params, &$smarty = null)
+    /** Build a link to a Banana page
+     * @param params ARRAY location datas
+     * @param smarty OBJECT Smarty instance associated (null if none)
+     * @return Link to the page associated with the given parameters
+     *
+     * Support all @ref makeURL parameters, but catch the following:
+     * - text     : if set, defined the text of the link (if not set, the URL is used
+     * - popup    : title of the link (showed as a tooltip on most browsers)
+     * - class    : specific style class for the markup
+     * - accesskey: keyboard key to trigger the link
+     * None of this parameters is needed
+     *
+     * Smarty function : {link param1=... param2=...}
+     */
+    public function makeLink(array $params, &$smarty = null)
     {
         $catch = array('text', 'popup', 'class', 'accesskey');
         foreach ($catch as $key) {
@@ -146,24 +199,33 @@ class BananaPage extends Smarty
             $popup .= ' (raccourci : ' . $accesskey . ')';
         }
         if (!is_null($popup)) {
-            $popup = ' title="' . $popup . '"';
+            $popup = ' title="' . banana_htmlentities($popup) . '"';
         }
         if (!is_null($class)) {
             $class = ' class="' . $class . '"';
         }
-        $target = null;
-        if (isset($params['action']) && $params['action'] == 'view') {
-            $target = ' target="_blank"';
-        }
         if (!is_null($accesskey)) {
             $accesskey = ' accesskey="' . $accesskey . '"';
         }
-        return '<a href="' . htmlentities($link) . '"'
-              . $target . $popup . $class . $accesskey
+        return '<a href="' . banana_htmlentities($link) . '"'
+              . $popup . $class . $accesskey
               . '>' . $text . '</a>';
     }
 
-    public function makeImg($params, &$smarty = null)
+    /** Build a link to one of the banana built-in images
+     * @param params ARRAY image datas
+     * @param smarty OBJECT Smarty instance associated (null if none)
+     * @return Img tag
+     *
+     * Supported parameters are
+     * - img : name of the image (without its extension)
+     * - alt : alternative text
+     * - height and width : dimensions of the images
+     * img and alt are needed
+     *
+     * Smarty function: {img img=... alt=... [height=...] [width=...]}
+     */
+    public function makeImg(array $params, &$smarty = null)
     {
         $catch = array('img', 'alt', 'height', 'width');
         foreach ($catch as $key) {
@@ -189,19 +251,35 @@ class BananaPage extends Smarty
 
         return '<img src="' . $url . '"' . $height . $width . ' alt="' . _b_($alt) . '" />';
     }
-
-    public function makeImgLink($params, &$smarty = null)
+    
+    /** Build a link with an image as text
+     * @param params ARRAY image and location data
+     * @param smarty OBJECT Smarty instance associated (null if none)
+     * @return an image within an link
+     *
+     * All @ref makeImg and @ref makeLink parameters are supported
+     * if text is set, the text will be appended after the image in the link
+     *
+     * Smarty function : {imglink img=... alt=... [param1=...]}
+     */
+    public function makeImgLink(array $params, &$smarty = null)
     {
         $params['alt'] = _b_($params['alt']);
-        $params['popup'] = $params['alt'];
-        $params['text'] = $this->makeImg($params, $smarty);
+        if (!isset($params['popup'])) {
+            $params['popup'] = $params['alt'];
+        }    
+        $img = $this->makeImg($params, $smarty);
+        if (isset($params['text'])) {
+            $img .= ' ' . $params['text'];
+        }
+        $params['text'] = $img;
         return $this->makeLink($params, $smarty);
     }
 
     /** Redirect to the page with the given parameter
-     * @ref makeLink
+     * @ref makeURL
      */
-    public function redirect($params = array())
+    public function redirect(array $params = array())
     {
         header('Location: ' . $this->makeUrl($params));
     }
diff --git a/banana/spool.inc.php b/banana/spool.inc.php
index 610d192..9514d6a 100644
--- a/banana/spool.inc.php
+++ b/banana/spool.inc.php
@@ -197,7 +197,7 @@ class BananaSpool
 
     private function update(&$first, &$last, $msgnum)
     {
-        if ($first >= $last || !$msgnum) {       
+        if ($first > $last || !$msgnum) {       
             return false;
         }
 
diff --git a/banana/templates/banana-base.tpl b/banana/templates/banana-base.tpl
index 3db7416..ba6a0b8 100644
--- a/banana/templates/banana-base.tpl
+++ b/banana/templates/banana-base.tpl
@@ -11,7 +11,7 @@
             <li class="actif">{$pg.text}</li>
             {assign var=current_page value=$pg}
           {else}
-            <li>{if $name eq 'subscribe'}{link subscribe=1 text=$pg.text}
+            <li>{if $name eq 'subscribe'}{link action=subscribe text=$pg.text}
             {elseif $name eq 'forums'}{link text=$pg.text}
             {elseif $name eq 'thread'}{link group=$group text=$group}
             {elseif $name eq 'message'}{link group=$group artid=$artid text=$pg.text}
@@ -27,6 +27,7 @@
       {foreach from=$errors item=error}
       <p class="error">{$error}</p>
       {/foreach}
+      {if !$killed}
       {foreach from=$actions item=act}
       <p class="center" style="padding: 0; margin: 0 0 1em 0">{$act.text}</p>
       {/foreach}
@@ -56,6 +57,7 @@
       {elseif $current_page.template}
         {include file=$current_page.template}
       {/if}
+      {/if}
     </td>
   </tr>
 </table>
diff --git a/banana/templates/banana-boxlist.inc.tpl b/banana/templates/banana-boxlist.inc.tpl
index 0331838..c0cb3ed 100644
--- a/banana/templates/banana-boxlist.inc.tpl
+++ b/banana/templates/banana-boxlist.inc.tpl
@@ -1,6 +1,6 @@
 {if $groups|@count}
 {if $withsubs}
-<form action="{url subscribe=1}" method="post">
+<form action="{url action=subscribe}" method="post">
 <p style="text-align: center">
   <input type="submit" name="validsubs" value="Valider" />
 </p>