phpBB

Development Wiki

Difference between revisions of "Build cfg template"

From phpBB Development Wiki

(Example #1)
 
(8 intermediate revisions by 4 users not shown)
Line 1: Line 1:
Function: '''build_cfg_template();'''
+
'''build_cfg_template();''' –– Build configuration template for the ACP.
  
This function is used in the ACP to build configuration pages and cuts down on all the INPUT fields and allows you to create a simple array of all the fields you need to set, along with limits, validation, etc...
+
{{stub}}
  
The main area to look at is the $display_vars['vars'] part of the array.
+
==Description==
 +
<pre>string build_cfg_template( $tpl_type , $key , &$new , $config_key , $vars)</pre>
 +
This function is used in the ACP to build a configuration page and cuts down on all the INPUT fields you have to make in the template.  It allows you to create a simple array of all the fields you need to set, along with limits, validation, etc...<br>
  
$display_vars['vars'][$config_key] => ''configuration_settings_array()''
+
This is done by building a $[[Build_cfg_template#display_vars_array|display_vars array]], looping through it and passing the data to the function.
  
This last array is the key to the configuration settings.
+
==Parameters==
 +
{|border="1" cellspacing="0" cellpadding="3"
 +
! Parameter
 +
! Usage
 +
|-
 +
| '''tpl_type'''
 +
|
 +
|-
 +
| '''key'''
 +
|
 +
|-
 +
|'''new'''
 +
|
 +
|-
 +
|'''config_key'''
 +
|
 +
|-
 +
|'''vars'''
 +
|
 +
|}
  
* '''$display_vars['vars'][$config_key]['lang']'''  
+
==Return Values==
** Text label
+
HTML string for output within the template.
* '''$display_vars['vars'][$config_key]['validate']'''  
+
 
** Expected data type.  Uses ':' as a delimiter to setup extended settings
+
==display_vars array==
*** bool
+
'''title'''<br>
*** int
+
ACP title<br><br>
*** lang
+
'''lang'''<br>
*** string
+
Include a different lang file<br><br>
*** wpath
+
'''vars array'''<br>
* '''$display_vars['vars'][$config_key]['type']'''  
+
Used to build form<br>
** Type of field.  Uses ':' as a delimiter to setup extended settings
+
{|border="1" cellspacing="0" cellpadding="3"
*** dimension
+
! Key
*** custom
+
! Description
*** password
+
! Valid Type
*** radio
+
|-
*** select
+
| '''lang'''
*** string
+
| Text label
*** text
+
|
*** textarea
+
|-
*** false
+
| '''validate'''
* '''$display_vars['vars'][$config_key]['explain']'''
+
| Expected data type
** Show explain text (true/false)
+
|
* '''$display_vars['vars'][$config_key]['method']'''
+
* bool
** A function inside your acp class to create screen output, generally used for optional elements <OPTION name=foo>FOO_LABEL</OPTION>
+
* int
* '''$display_vars['vars'][$config_key]['function']'''
+
* lang
** A function not inside your acp class to create screen output, generally used for optional elements <OPTION name=foo>FOO_LABEL</OPTION>
+
* string
* '''$display_vars['vars'][$config_key]['params']'''
+
* wpath
** Input parameters to use with the function or method
+
|-
* '''$display_vars['vars'][$config_key]['append']'''
+
| '''type'''
** Any text that follows the form field
+
| Type of field
 +
|
 +
* dimension
 +
* custom
 +
* password
 +
* radio
 +
* select
 +
* string
 +
* text
 +
* textarea
 +
* false
 +
|-
 +
| '''explain'''
 +
| Show explain text
 +
|
 +
* false
 +
* true
 +
|-
 +
| '''method'''
 +
| A function inside your acp class to create screen output, generally used for optional elements <OPTION name=foo>FOO_LABEL</OPTION>
 +
|
 +
|-
 +
| '''function'''
 +
| A function not inside your acp class to create screen output, generally used for optional elements <OPTION name=foo>FOO_LABEL</OPTION>
 +
|
 +
|-
 +
| '''params'''
 +
| Input parameters to use with the function or method
 +
|
 +
|-
 +
| '''append'''
 +
| Any text that follows the form field
 +
|
 +
|}
 +
 
 +
==Examples==
 +
===Example #1===
 +
<php>$display_vars = array(
 +
'title' => 'ACP_FOO',
 +
'vars' => array(
 +
'legend1' => 'GENERAL_FOO',
 +
'foo1' => array('lang' => 'ALLOW_BAR',  'validate' => 'bool',   'type' => 'radio:yes_no',  'explain' => false),
 +
'foo2' => array('lang' => 'MAX_BAR',   'validate' => 'int:0',  'type' => 'text:5:4',   'explain' => true),
 +
'foo3' => array('lang' => 'BAR_TYPE',   'validate' => 'string',  'type' => 'custom',   'method' => 'bar_type', 'explain' => true),
 +
'foo4' => array('lang' => 'SELECT_EXAMPLE', 'validate' => 'int', 'type' => 'select', 'function' => 'style_select', 'params' => array('{CONFIG_VALUE}', false), 'explain' => false)
 +
),
 +
);
 +
 
 +
$this->new_config = $config;
 +
$cfg_array = (isset($_REQUEST['config'])) ? request_var('config', array('' => '')) : $this->new_config;
 +
$error = array();
 +
 
 +
validate_config_vars($display_vars['vars'], $cfg_array, $error);
 +
 
 +
foreach ($display_vars['vars'] as $config_key => $vars)
 +
{
 +
if (!is_array($vars) && strpos($config_key, 'legend') === false)
 +
{
 +
continue;
 +
}
 +
 
 +
if (strpos($config_key, 'legend') !== false)
 +
{
 +
$template->assign_block_vars('options', array(
 +
'S_LEGEND' => true,
 +
'LEGEND' => (isset($user->lang[$vars])) ? $user->lang[$vars] : $vars)
 +
);
 +
 
 +
continue;
 +
}
 +
 
 +
$type = explode(':', $vars['type']);
 +
 
 +
$l_explain = '';
 +
if ($vars['explain'] && isset($vars['lang_explain']))
 +
{
 +
$l_explain = (isset($user->lang[$vars['lang_explain']])) ? $user->lang[$vars['lang_explain']] : $vars['lang_explain'];
 +
}
 +
else if ($vars['explain'])
 +
{
 +
$l_explain = (isset($user->lang[$vars['lang'] . '_EXPLAIN'])) ? $user->lang[$vars['lang'] . '_EXPLAIN'] : '';
 +
}
 +
 
 +
$content = build_cfg_template($type, $config_key, $this->new_config, $config_key, $vars);
 +
 
 +
if (empty($content))
 +
{
 +
continue;
 +
}
 +
 
 +
$template->assign_block_vars('options', array(
 +
'KEY' => $config_key,
 +
'TITLE' => (isset($user->lang[$vars['lang']])) ? $user->lang[$vars['lang']] : $vars['lang'],
 +
'S_EXPLAIN' => $vars['explain'],
 +
'TITLE_EXPLAIN' => $l_explain,
 +
'CONTENT' => $content,
 +
));
 +
 
 +
unset($display_vars['vars'][$config_key]);
 +
}
 +
 
 +
function style_select($default = '', $all = false)
 +
{
 +
global $db;
 +
 
 +
$sql_where = (!$all) ? 'WHERE style_active = 1 ' : '';
 +
$sql = 'SELECT style_id, style_name
 +
FROM ' . STYLES_TABLE . "
 +
$sql_where
 +
ORDER BY style_name";
 +
$result = $db->sql_query($sql);
 +
 
 +
$style_options = '';
 +
while ($row = $db->sql_fetchrow($result))
 +
{
 +
$selected = ($row['style_id'] == $default) ? ' selected="selected"' : '';
 +
$style_options .= '<option value="' . $row['style_id'] . '"' . $selected . '>' . $row['style_name'] . '</option>';
 +
}
 +
$db->sql_freeresult($result);
 +
 
 +
return $style_options;
 +
}
 +
 
 +
</php><br>
 +
 
 +
'''Template'''<br>
 +
<php><!-- BEGIN options -->
 +
<!-- IF options.S_LEGEND -->
 +
<!-- IF not options.S_FIRST_ROW -->
 +
</fieldset>
 +
<!-- ENDIF -->
 +
<fieldset>
 +
<legend>{options.LEGEND}</legend>
 +
<!-- ELSE -->
 +
 
 +
<dl>
 +
<dt><label for="{options.KEY}">{options.TITLE}:</label><!-- IF options.S_EXPLAIN --><br /><span>{options.TITLE_EXPLAIN}</span><!-- ENDIF --></dt>
 +
<dd>{options.CONTENT}</dd>
 +
</dl>
 +
 
 +
<!-- ENDIF -->
 +
<!-- END options --></php>
 +
<br>
 +
 
 +
==See Also==
 +
* [[Creating modules]]
 +
* [[ACP]]
 +
<br><br>
  
 
[[Category:API]]
 
[[Category:API]]
 
[[Category:Concepts]]
 
[[Category:Concepts]]
 +
 +
[[ja:Build_cfg_template]]

Latest revision as of 05:14, 6 May 2009

build_cfg_template(); –– Build configuration template for the ACP.

This article is a stub. You can help in improving Olympus Documentation by expanding it.


Description

string build_cfg_template( $tpl_type , $key , &$new , $config_key , $vars)

This function is used in the ACP to build a configuration page and cuts down on all the INPUT fields you have to make in the template. It allows you to create a simple array of all the fields you need to set, along with limits, validation, etc...

This is done by building a $display_vars array, looping through it and passing the data to the function.

Parameters

Parameter Usage
tpl_type
key
new
config_key
vars

Return Values

HTML string for output within the template.

display_vars array

title
ACP title

lang
Include a different lang file

vars array
Used to build form

Key Description Valid Type
lang Text label
validate Expected data type
  • bool
  • int
  • lang
  • string
  • wpath
type Type of field
  • dimension
  • custom
  • password
  • radio
  • select
  • string
  • text
  • textarea
  • false
explain Show explain text
  • false
  • true
method A function inside your acp class to create screen output, generally used for optional elements <OPTION name=foo>FOO_LABEL</OPTION>
function A function not inside your acp class to create screen output, generally used for optional elements <OPTION name=foo>FOO_LABEL</OPTION>
params Input parameters to use with the function or method
append Any text that follows the form field

Examples

Example #1

$display_vars = array(
    
'title' => 'ACP_FOO',
    
'vars'    => array(
        
'legend1'             => 'GENERAL_FOO',
        
'foo1'                 => array('lang' => 'ALLOW_BAR',  'validate' => 'bool',          'type' => 'radio:yes_no',   'explain' => false),
        
'foo2'                => array('lang' => 'MAX_BAR',      'validate' => 'int:0',       'type' => 'text:5:4',       'explain' => true),
        
'foo3'                => array('lang' => 'BAR_TYPE',      'validate' => 'string',      'type' => 'custom',       'method' => 'bar_type''explain' => true),
        
'foo4'                => array('lang' => 'SELECT_EXAMPLE''validate' => 'int',    'type' => 'select''function' => 'style_select''params' => array('{CONFIG_VALUE}'false), 'explain' => false)
    ),
);

$this->new_config $config;
$cfg_array = (isset($_REQUEST['config'])) ? request_var('config', array('' => '')) : $this->new_config;
$error = array();

validate_config_vars($display_vars['vars'], $cfg_array$error);

foreach (
$display_vars['vars'] as $config_key => $vars)
{
    if (!
is_array($vars) && strpos($config_key'legend') === false)
    {
        continue;
    }

    if (
strpos($config_key'legend') !== false)
    {
        
$template->assign_block_vars('options', array(
            
'S_LEGEND'        => true,
            
'LEGEND'        => (isset($user->lang[$vars])) ? $user->lang[$vars] : $vars)
        );

        continue;
    }

    
$type explode(':'$vars['type']);

    
$l_explain '';
    if (
$vars['explain'] && isset($vars['lang_explain']))
    {
        
$l_explain = (isset($user->lang[$vars['lang_explain']])) ? $user->lang[$vars['lang_explain']] : $vars['lang_explain'];
    }
    else if (
$vars['explain'])
    {
        
$l_explain = (isset($user->lang[$vars['lang'] . '_EXPLAIN'])) ? $user->lang[$vars['lang'] . '_EXPLAIN'] : '';
    }

    
$content build_cfg_template($type$config_key$this->new_config$config_key$vars);

    if (empty(
$content))
    {
        continue;
    }

    
$template->assign_block_vars('options', array(
        
'KEY'            => $config_key,
        
'TITLE'            => (isset($user->lang[$vars['lang']])) ? $user->lang[$vars['lang']] : $vars['lang'],
        
'S_EXPLAIN'        => $vars['explain'],
        
'TITLE_EXPLAIN' => $l_explain,
        
'CONTENT'        => $content,
    ));

    unset(
$display_vars['vars'][$config_key]);
}

function 
style_select($default ''$all false)
{
    global 
$db;

    
$sql_where = (!$all) ? 'WHERE style_active = 1 ' '';
    
$sql 'SELECT style_id, style_name
        FROM ' 
STYLES_TABLE "
        
$sql_where
        ORDER BY style_name"
;
    
$result $db->sql_query($sql);

    
$style_options '';
    while (
$row $db->sql_fetchrow($result))
    {
        
$selected = ($row['style_id'] == $default) ? ' selected="selected"' '';
        
$style_options .= '<option value="' $row['style_id'] . '"' $selected '>' $row['style_name'] . '</option>';
    }
    
$db->sql_freeresult($result);

    return 
$style_options;
}

Template

<!-- BEGIN options -->
    <!-- IF 
options.S_LEGEND -->
        <!-- IF 
not options.S_FIRST_ROW -->
            </
fieldset>
        <!-- ENDIF -->
        <
fieldset>
            <
legend>{options.LEGEND}</legend>
    <!-- ELSE -->

        <
dl>
            <
dt><label for="{options.KEY}">{options.TITLE}:</label><!-- IF options.S_EXPLAIN --><br /><span>{options.TITLE_EXPLAIN}</span><!-- ENDIF --></dt>
            <
dd>{options.CONTENT}</dd>
        </
dl>

    <!-- ENDIF -->
<!-- 
END options -->


See Also