      1: <?php
      2:
      3: /**
      4:  * Defines the renderer interface, which allows us to have various implementations (HTML,
      5:  * JSON, XML etc.) behind one unified interface.  Use the
      6:  * AlphaRendererProviderFactory::getInstance() method to get instances of this.
      7:  *
      8:  * @package alpha::view::renderers
      9:  * @since 1.2
     10:  * @author John Collins <dev@alphaframework.org>
     11:  * @version $Id: AlphaRendererProviderInterface.inc 1633 2013-01-22 16:43:56Z alphadevx $
     12:  * @license http://www.opensource.org/licenses/bsd-license.php The BSD License
     13:  * @copyright Copyright (c) 2012, John Collins (founder of Alpha Framework).
     14:  * All rights reserved.
     15:  *
     16:  * <pre>
     17:  * Redistribution and use in source and binary forms, with or
     18:  * without modification, are permitted provided that the
     19:  * following conditions are met:
     20:  *
     21:  * * Redistributions of source code must retain the above
     22:  *   copyright notice, this list of conditions and the
     23:  *   following disclaimer.
     24:  * * Redistributions in binary form must reproduce the above
     25:  *   copyright notice, this list of conditions and the
     26:  *   following disclaimer in the documentation and/or other
     27:  *   materials provided with the distribution.
     28:  * * Neither the name of the Alpha Framework nor the names
     29:  *   of its contributors may be used to endorse or promote
     30:  *   products derived from this software without specific
     31:  *   prior written permission.
     32:  *
     33:  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
     34:  * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
     35:  * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
     36:  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
     37:  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
     38:  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
     39:  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
     40:  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
     41:  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
     42:  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
     43:  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
     44:  * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
     45:  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     46:  * </pre>
     47:  *
     48:  */
     49: interface AlphaRendererProviderInterface {
     50:     /**
     51:      * Provide the BO that we are going render.
     52:      *
     53:      * @param AlphaDAO $BO
     54:      * @since 1.2
     55:      */
     56:     public function setBO($BO);
     57:
     58:     /**
     59:      * Renders the create view for the BO using the selected renderer.
     60:      *
     61:      * @param array $fields Hash array of fields to pass to the template.
     62:      * @return string
     63:      * @since 1.2
     64:      */
     65:     public function createView($fields=array());
     66:
     67:     /**
     68:      * Renders the edit view for the BO using the selected renderer.
     69:      *
     70:      * @param array $fields Hash array of fields to pass to the template.
     71:      * @return string
     72:      * @since 1.2
     73:      */
     74:     public function editView($fields=array());
     75:
     76:     /**
     77:      * Renders the list view for the BO using the selected renderer.
     78:      *
     79:      * @param array $fields Hash array of fields to pass to the template.
     80:      * @return string
     81:      * @since 1.2
     82:      */
     83:     public function listView($fields=array());
     84:
     85:     /**
     86:      * Renders the detailed read-only view for the BO using the selected renderer.
     87:      *
     88:      * @param array $fields Hash array of fields to pass to the template.
     89:      * @return string
     90:      * @since 1.2
     91:      */
     92:     public function detailedView($fields=array());
     93:
     94:     /**
     95:      * Renders the admin view for the BO using the selected renderer.
     96:      *
     97:      * @param array $fields Hash array of fields to pass to the template.
     98:      * @return string
     99:      * @since 1.2
    100:      */
    101:     public function adminView($fields=array());
    102:
    103:     /**
    104:      * Renders the header content using the given renderer.
    105:      *
    106:      * @param AlphaController $controller
    107:      * @return string
    108:      * @throws IllegalArguementException
    109:      * @since 1.2
    110:      */
    111:     public static function displayPageHead($controller);
    112:
    113:     /**
    114:      * Renders the footer content using the given renderer.
    115:      *
    116:      * @param AlphaController $controller
    117:      * @return string
    118:      * @since 1.2
    119:      */
    120:     public static function displayPageFoot($controller);
    121:
    122:     /**
    123:      * Renders an update (e.g. successful save) message.
    124:      *
    125:      * @param string $message
    126:      * @return string
    127:      * @since 1.2
    128:      */
    129:     public static function displayUpdateMessage($message);
    130:
    131:     /**
    132:      * Renders an error (e.g. save failed) message.
    133:      *
    134:      * @param string $message
    135:      * @return string
    136:      * @since 1.2
    137:      */
    138:     public static function displayErrorMessage($message);
    139:
    140:     /**
    141:      * Renders an error page with the supplied HTTP error code and a message.
    142:      *
    143:      * @param string $code
    144:      * @param string $message
    145:      * @return string
    146:      * @since 1.2
    147:      */
    148:     public static function renderErrorPage($code, $message);
    149:
    150:     /**
    151:      * Method to render a hidden HTML form for posting the OID of an object to be deleted.
    152:      *
    153:      * @return string
    154:      * @since 1.2
    155:      */
    156:     public static function renderDeleteForm();
    157:
    158:     /**
    159:      * Method to render a HTML form with two hidden, hashed (MD5) form fields to be used as
    160:      * a check to ensure that a post to the controller is being sent from the same server
    161:      * as hosting it.
    162:      *
    163:      * @return string
    164:      * @since 1.2
    165:      */
    166:     public static function renderSecurityFields();
    167:
    168:     /**
    169:      * Renders an Integer field value.
    170:      *
    171:      * @param string $name The field name
    172:      * @param string $label The label to apply to the field
    173:      * @param string $mode The field mode (create/edit/view)
    174:      * @param string $value The field value (optional)
    175:      * @param bool $tableTags Include table tags and label (optional)
    176:      * @return string
    177:      * @since 1.2
    178:      */
    179:     public function renderIntegerField($name, $label, $mode, $value='', $tableTags=true);
    180:
    181:     /**
    182:      * Renders an Double field value.
    183:      *
    184:      * @param string $name The field name
    185:      * @param string $label The label to apply to the field
    186:      * @param string $mode The field mode (create/edit/view)
    187:      * @param string $value The field value (optional)
    188:      * @param bool $tableTags Include table tags and label (optional)
    189:      * @return string
    190:      * @since 1.2
    191:      */
    192:     public function renderDoubleField($name, $label, $mode, $value='', $tableTags=true);
    193:
    194:     /**
    195:      * Renders an Boolean field value.
    196:      *
    197:      * @param string $name The field name
    198:      * @param string $label The label to apply to the field
    199:      * @param string $mode The field mode (create/edit/view)
    200:      * @param string $value The field value (optional)
    201:      * @param bool $tableTags Include table tags and label (optional)
    202:      * @return string
    203:      * @since 1.2
    204:      */
    205:     public function renderBooleanField($name, $label, $mode, $value='', $tableTags=true);
    206:
    207:     /**
    208:      * Renders an Enum field value.
    209:      *
    210:      * @param string $name The field name
    211:      * @param string $label The label to apply to the field
    212:      * @param string $mode The field mode (create/edit/view)
    213:      * @param array $options The Enum options
    214:      * @param string $value The field value (optional)
    215:      * @param bool $tableTags Include table tags and label (optional)
    216:      * @return string
    217:      * @since 1.0
    218:      */
    219:     public function renderEnumField($name, $label, $mode, $options, $value='', $tableTags=true);
    220:
    221:     /**
    222:      * Renders an DEnum field value.
    223:      *
    224:      * @param string $name The field name
    225:      * @param string $label The label to apply to the field
    226:      * @param string $mode The field mode (create/edit/view)
    227:      * @param array $options The DEnum options
    228:      * @param string $value The field value (optional)
    229:      * @param bool $tableTags Include table tags and label (optional)
    230:      * @return string
    231:      * @since 1.2
    232:      */
    233:     public function renderDEnumField($name, $label, $mode, $options, $value='', $tableTags=true);
    234:
    235:     /**
    236:      * Method to render a field when type is not known.
    237:      *
    238:      * @param string $name The field name
    239:      * @param string $label The label to apply to the field
    240:      * @param string $mode The field mode (create/edit/view)
    241:      * @param string $value The field value (optional)
    242:      * @param bool $tableTags Include table tags and label (optional)
    243:      * @return string
    244:      * @since 1.2
    245:      */
    246:     public function renderDefaultField($name, $label, $mode, $value='', $tableTags=true);
    247:
    248:     /**
    249:      * Renders a Text field value.
    250:      *
    251:      * @param string $name The field name
    252:      * @param string $label The label to apply to the field
    253:      * @param string $mode The field mode (create/edit/view)
    254:      * @param string $value The field value (optional)
    255:      * @param bool $tableTags Include table tags and label (optional)
    256:      * @return string
    257:      * @since 1.0
    258:      */
    259:     public function renderTextField($name, $label, $mode, $value='', $tableTags=true);
    260:
    261:     /**
    262:      * Renders a String field value.
    263:      *
    264:      * @param string $name The field name
    265:      * @param string $label The label to apply to the field
    266:      * @param string $mode The field mode (create/edit/view)
    267:      * @param string $value The field value (optional)
    268:      * @param bool $tableTags Include table tags and label (optional)
    269:      * @return string
    270:      * @since 1.2.2
    271:      */
    272:     public function renderStringField($name, $label, $mode, $value='', $tableTags=true);
    273:
    274:     /**
    275:      * Renders a Relation field value.
    276:      *
    277:      * @param string $name The field name
    278:      * @param string $label The label to apply to the field
    279:      * @param string $mode The field mode (create/edit/view)
    280:      * @param string $value The field value (optional)
    281:      * @param bool $tableTags Include table tags and label (optional)
    282:      * @param bool $expanded Render the related fields in expanded format or not (optional)
    283:      * @param bool $buttons Render buttons for expanding/contacting the related fields (optional)
    284:      * @return string
    285:      * @since 1.2
    286:      */
    287:     public function renderRelationField($name, $label, $mode, $value='', $tableTags=true, $expanded=false, $buttons=true);
    288:
    289:     /**
    290:      * Convenience method that renders all fields for the current BO in edit/create/view mode.
    291:      *
    292:      * @param string $mode (view|edit|create)
    293:      * @param array $filterFields Optional list of field names to exclude from rendering.
    294:      * @param array $readOnlyFields Optional list of fields to render in a readonly fashion when rendering in create or edit mode.
    295:      * @return string
    296:      * @since 1.2
    297:      */
    298:     public function renderAllFields($mode, $filterFields=array(), $readOnlyFields=array());
    299: }
    300:
    301: ?>
    302: