Actions

Difference between revisions of "BasicPHPFileTemplates"

From Mahara Wiki

 
(8 intermediate revisions by 2 users not shown)
Line 5: Line 5:
 
==Template for files you expect to be hit by visitors==
 
==Template for files you expect to be hit by visitors==
  
.
+
<source lang="php" enclose="div">
/**
+
/**
  *
+
*
  * @package    mahara
+
* @package    mahara
  * @subpackage core or plugintype/pluginname
+
* @subpackage core or plugintype/pluginname
  * @author    Firstname Lastname
+
* @author    Firstname Lastname
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL version 3 or later
+
* @license    http://www.gnu.org/copyleft/gpl.html GNU GPL version 3 or later
  * @copyright  For copyright information on Mahara, please see the README file distributed with this software.
+
* @copyright  For copyright information on Mahara, please see the README file distributed with this software.
  *
+
*
  */
+
*/
+
 
  define('INTERNAL', 1);
+
define('INTERNAL', 1);
  require('init.php');
+
require('init.php');
+
 
  // Your code here :)
+
// Your code here :)
 +
</source>
  
 
==Template for files you do NOT want to be hit by visitors==
 
==Template for files you do NOT want to be hit by visitors==
  
.
+
<source lang="php" enclose="div">
/**
+
/**
  * Mahara: Electronic portfolio, weblog, resume builder and social networking
+
*
  * Copyright (C) 2011 Copyright Holder
+
* @package    mahara
  *
+
* @subpackage core or plugintype/pluginname
  * (rest of the GPL statement)
+
* @author    Firstname Lastname
  *
+
* @license   http://www.gnu.org/copyleft/gpl.html GNU GPL version 3 or later
  * @package    mahara
+
* @copyright  For copyright information on Mahara, please see the README file distributed with this software.
  * @subpackage core or plugintype/pluginname
+
*
  * @author    Firstname Lastname
+
*/
   */
+
 
+
defined('INTERNAL') || die();
  defined('INTERNAL') || die();
+
 
+
// Your code here :)
  // Your code here :)
+
</source>
 
   
 
   
  
Line 48: Line 49:
 
== Sample page using pieforms and dwoo ==
 
== Sample page using pieforms and dwoo ==
  
<?php
+
<source lang="php" enclose="div">
+
<?php
define('INTERNAL', 1);
+
 
require('init.php');
+
define('INTERNAL', 1);
require_once('pieforms/pieform.php');
+
require('init.php');
+
require_once('pieforms/pieform.php');
// Get data from the user by using the param_ functions, which will whitelist
+
 
// the input
+
// Get data from the user by using the param_ functions, which will whitelist
$userint = param_integer('int',0);
+
// the input
// If none of the whitelisting options is acceptable, you can use param_variable,
+
$userint = param_integer('int',0);
// but be careful not to print the results to the screen without cleaning them
+
// If none of the whitelisting options is acceptable, you can use param_variable,
// first. That's a XSS vulnerability.
+
// but be careful not to print the results to the screen without cleaning them
$userraw = param_variable('raw', 'no user input provided');
+
// first. That's a XSS vulnerability.
+
$userraw = param_variable('raw', 'no user input provided');
// Generate page content
+
 
// NOTE: Normally you should put hard-coded strings into a lang file under /lang, so that
+
// Generate page content
// they can be internationalized with get_string()
+
// NOTE: Normally you should put hard-coded strings into a lang file under /lang, so that
$hardcoded = "This is a hard-coded string";
+
// they can be internationalized with get_string()
+
$hardcoded = "This is a hard-coded string";
// See https://wiki.mahara.org/index.php/Developer_Area/Core_Subsystems/Form_API_%28Pieforms%29
+
 
// Normally you'd populate the default values with values from the DB
+
// See https://wiki.mahara.org/index.php/Developer_Area/Core_Subsystems/Form_API_%28Pieforms%29
$form = array(
+
// Normally you'd populate the default values with values from the DB
    'name' => 'testform',
+
$form = array(
    'method' => 'post',
+
    'name' => 'testform',
    'action' => '', // self
+
    'method' => 'post',
    'successcallback' => 'testform_submit', // defaults to name_submit
+
    'action' => "", // self
    'validatecallback' => 'testform_validate', // defaults to name_validate
+
    'successcallback' => 'testform_submit', // defaults to name_submit
    'elements' => array(
+
    'validatecallback' => 'testform_validate', // defaults to name_validate
        'fullname' => array(
+
    'elements' => array(
            'type' => 'fieldset',
+
        'fullname' => array(
            'legend' => "Your name", // should use get_string()...
+
            'type' => 'fieldset',
            'elements' => array(
+
            'legend' => "Your name", // should use get_string()...
                'firstname' => array(
+
            'elements' => array(
                    'type' => 'text',
+
                'firstname' => array(
                    'title' => "First name", // should use get_string()
+
                    'type' => 'text',
                    'description' => "Your first, or given name", // get_string()
+
                    'title' => "First name", // should use get_string()
                    'help' => "Surely you know your own first name.", // get_string()
+
                    'description' => "Your first, or given name", // get_string()
                    'defaultvalue' => 'Joe',
+
                    'help' => "Surely you know your own first name.", // get_string()
                    'rules' => array(
+
                    'defaultvalue' => 'Joe',
                        'required' => true
+
                    'rules' => array(
                    )
+
                        'required' => true
                ),
+
                    )
                'lastname' => array(
+
                ),
                    'type' => 'text',
+
                'lastname' => array(
                    'title' => "Last name", // get_string()
+
                    'type' => 'text',
                    'defaultvalue' => 'Schmoe',
+
                    'title' => "Last name", // get_string()
                    'description' => "Your last, or family name", // get_string()
+
                    'defaultvalue' => 'Schmoe',
                )
+
                    'description' => "Your last, or family name", // get_string()
            )
+
                )
        ),
+
            )
        'submitbtn' => array(
+
        ),
            'type' => 'submit',
+
        'submitbtn' => array(
            'value' => "Submit" // get_string()
+
            'type' => 'submit',
        )
+
            'value' => "Submit" // get_string()
    )
+
        )
);
+
    )
+
);
function testform_validate(Pieform $form, $values) {
+
 
    if (isset($values['lastname']) && $values['firstname'] == 'Joe' && $values['lastname'] == 'Schmoe') {
+
function testform_validate(Pieform $form, $values) {
        $form->set_error('lastname', "That's not your real name! That was the default."); // get_string()
+
    if (isset($values['lastname']) && $values['firstname'] == 'Joe' && $values['lastname'] == 'Schmoe') {
    }
+
        $form->set_error('lastname', "That's not your real name! That was the default."); // get_string()
}
+
    }
+
}
function testform_submit(Pieform $form, $values) {
+
 
    global $SESSION;
+
function testform_submit(Pieform $form, $values) {
    // Normally here you would save the submitted values into the database
+
    global $SESSION;
+
    // Normally here you would save the submitted values into the database
    // If you set this up as a JS form, use json_reply()
+
 
    if (!empty($values['lastname'])) {
+
    // If you set this up as a JS form, use json_reply()
        $name = "{$values['firstname']} {$values['lastname']}";
+
    if (!empty($values['lastname'])) {
    } else {
+
        $name = "{$values['firstname']} {$values['lastname']}";
        $name = $values['firstname'];
+
    } else {
    }
+
        $name = $values['firstname'];
    $SESSION->add_ok_msg("Kia ora, {$name}!");
+
    }
    redirect(get_config('wwwroot') . 'test.php');
+
    $SESSION->add_ok_msg("Kia ora, {$name}!");
}
+
    redirect(get_config('wwwroot') . 'test.php');
+
}
// When you call pieform(), the Pieforms library does a bunch of automagical stuff.
+
 
// It checks whether the form was submitted, and if so calls the form's validate
+
// When you call pieform(), the Pieforms library does a bunch of automagical stuff.
// and/or submit callback functions, which usually results in a call to redirect(), ending
+
// It checks whether the form was submitted, and if so calls the form's validate
// the page load.
+
// and/or submit callback functions, which usually results in a call to redirect(), ending
// If the form wasn't yet submitted, then pieform() renders the form into the necessary
+
// the page load.
// HTML to print it on the page.
+
// If the form wasn't yet submitted, then pieform() renders the form into the necessary
// IMPORTANT: all pieform rendering needs to happen before calling smarty() for javascript
+
// HTML to print it on the page.
// to be added to the page correctly
+
// IMPORTANT: all pieform rendering needs to happen before calling smarty() for javascript
$formhtml = pieform($form);
+
// to be added to the page correctly
+
$formhtml = pieform($form);
// Instantiate the smarty object.
+
 
$smarty = smarty();
+
// Instantiate the smarty object.
// Variables you assign to the smarty become accessible in the template
+
$smarty = smarty();
$smarty->assign('hard_coded', $hardcoded);
+
// Variables you assign to the smarty become accessible in the template
$smarty->assign('user_raw', $userraw);
+
$smarty->assign('hard_coded', $hardcoded);
+
$smarty->assign('user_raw', $userraw);
$smarty->assign('form', $formhtml);
+
 
+
$smarty->assign('form', $formhtml);
// Specify the template file path, relative to htdocs/theme/raw/templates/
+
 
$smarty->display('test.tpl');
+
// Specify the template file path, relative to htdocs/theme/raw/templates/
+
$smarty->display('test.tpl');
/* The contents of htdocs/theme/raw/templates/test.tpl should look like this:
+
</source>
{include file="header.tpl"}
+
 
&lt;!-- Stuff in here is HTML except for the bits in curly braces -->
+
The contents of htdocs/theme/raw/templates/test.tpl should look like this:
+
 
&lt;!-- All variables printed here are run through an HTML escaping process, unless
+
<source lang="smarty" enclose="div">
they have the "|safe" tag. -->
+
{include file="header.tpl"}
{$hard_coded|safe}
+
<!-- Stuff in here is HTML except for the bits in curly braces -->
+
 
&lt;!-- Uncleaned user data shouldn't be considered safe -->
+
<!-- All variables printed here are run through an HTML escaping process, unless
{$user_raw}
+
they have the "|safe" tag. -->
+
{$hard_coded|safe}
&lt;!-- Any function in the calling PHP file's namespace can be invoked by adding
+
 
it after a "|" in the curly brackets -->
+
<!-- Uncleaned user data shouldn't be considered safe -->
{$hard_coded|strtoupper}
+
{$user_raw}
+
 
&lt;!-- The output from pieform() is the HTML output of the form. So you can just print it. -->
+
<!-- Any function in the calling PHP file's namespace can be invoked by adding
{$form|safe}
+
it after a "|" in the curly brackets -->
{include file="footer.tpl"}
+
{$hard_coded|strtoupper}
  */
+
 
 +
<!-- The output from pieform() is the HTML output of the form. So you can just print it. -->
 +
{$form|safe}
 +
{include file="footer.tpl"}
 +
</source>

Latest revision as of 15:43, 12 March 2014

These are the templates for all new PHP files. There is a different template depending on whether you file is able to be publicly hittable or not.

This project uses PHPDoc for API documentation. This project is also licensed under the GPL, which causes some header bloat (it is a requirement of licensing your program under the GPL, see http://www.gnu.org/copyleft/gpl.html ).

Template for files you expect to be hit by visitors

/**
 *
 * @package    mahara
 * @subpackage core or plugintype/pluginname
 * @author     Firstname Lastname
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL version 3 or later
 * @copyright  For copyright information on Mahara, please see the README file distributed with this software.
 *
 */

define('INTERNAL', 1);
require('init.php');

// Your code here :)

Template for files you do NOT want to be hit by visitors

/**
 *
 * @package    mahara
 * @subpackage core or plugintype/pluginname
 * @author     Firstname Lastname
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL version 3 or later
 * @copyright  For copyright information on Mahara, please see the README file distributed with this software.
 *
 */

defined('INTERNAL') || die();

// Your code here :)


Notes:

  • Omit the closing php tag "?>"
  • Catalyst employees should assign copyright to "Catalyst IT Ltd", if they are working on the project in company time.
  • The author field should always be a person (or more than one), not a company

Sample page using pieforms and dwoo

<?php

define('INTERNAL', 1);
require('init.php');
require_once('pieforms/pieform.php');

// Get data from the user by using the param_ functions, which will whitelist
// the input
$userint = param_integer('int',0);
// If none of the whitelisting options is acceptable, you can use param_variable,
// but be careful not to print the results to the screen without cleaning them
// first. That's a XSS vulnerability.
$userraw = param_variable('raw', 'no user input provided');

// Generate page content
// NOTE: Normally you should put hard-coded strings into a lang file under /lang, so that
// they can be internationalized with get_string()
$hardcoded = "This is a hard-coded string";

// See https://wiki.mahara.org/index.php/Developer_Area/Core_Subsystems/Form_API_%28Pieforms%29
// Normally you'd populate the default values with values from the DB
$form = array(
    'name' => 'testform',
    'method' => 'post',
    'action' => "", // self
    'successcallback' => 'testform_submit', // defaults to name_submit
    'validatecallback' => 'testform_validate', // defaults to name_validate
    'elements' => array(
        'fullname' => array(
            'type' => 'fieldset',
            'legend' => "Your name", // should use get_string()...
            'elements' => array(
                'firstname' => array(
                    'type' => 'text',
                    'title' => "First name", // should use get_string()
                    'description' => "Your first, or given name", // get_string()
                    'help' => "Surely you know your own first name.", // get_string()
                    'defaultvalue' => 'Joe',
                    'rules' => array(
                        'required' => true
                    )
                ),
                'lastname' => array(
                    'type' => 'text',
                    'title' => "Last name", // get_string()
                    'defaultvalue' => 'Schmoe',
                    'description' => "Your last, or family name", // get_string()
                )
            )
        ),
        'submitbtn' => array(
            'type' => 'submit',
            'value' => "Submit" // get_string()
        )
    )
);

function testform_validate(Pieform $form, $values) {
    if (isset($values['lastname']) && $values['firstname'] == 'Joe' && $values['lastname'] == 'Schmoe') {
        $form->set_error('lastname', "That's not your real name! That was the default."); // get_string()
    }
}

function testform_submit(Pieform $form, $values) {
    global $SESSION;
    // Normally here you would save the submitted values into the database

    // If you set this up as a JS form, use json_reply()
    if (!empty($values['lastname'])) {
        $name = "{$values['firstname']} {$values['lastname']}";
    } else {
        $name = $values['firstname'];
    }
    $SESSION->add_ok_msg("Kia ora, {$name}!");
    redirect(get_config('wwwroot') . 'test.php');
}

// When you call pieform(), the Pieforms library does a bunch of automagical stuff.
// It checks whether the form was submitted, and if so calls the form's validate
// and/or submit callback functions, which usually results in a call to redirect(), ending
// the page load.
// If the form wasn't yet submitted, then pieform() renders the form into the necessary
// HTML to print it on the page.
// IMPORTANT: all pieform rendering needs to happen before calling smarty() for javascript
// to be added to the page correctly
$formhtml = pieform($form);

// Instantiate the smarty object.
$smarty = smarty();
// Variables you assign to the smarty become accessible in the template
$smarty->assign('hard_coded', $hardcoded);
$smarty->assign('user_raw', $userraw);

$smarty->assign('form', $formhtml);

// Specify the template file path, relative to htdocs/theme/raw/templates/
$smarty->display('test.tpl');

The contents of htdocs/theme/raw/templates/test.tpl should look like this:

{include file="header.tpl"}
<!-- Stuff in here is HTML except for the bits in curly braces -->

<!-- All variables printed here are run through an HTML escaping process, unless
they have the "|safe" tag. -->
{$hard_coded|safe}

<!-- Uncleaned user data shouldn't be considered safe -->
{$user_raw}

<!-- Any function in the calling PHP file's namespace can be invoked by adding
it after a "|" in the curly brackets -->
{$hard_coded|strtoupper}

<!-- The output from pieform() is the HTML output of the form. So you can just print it. -->
{$form|safe}
{include file="footer.tpl"}