phpBB

Development Wiki

Difference between revisions of "Generate text for storage"

From phpBB Development Wiki

(Update with the information of the return values)
(1st example, how to store new data using generate_text_for_storage())
Line 52: Line 52:
 
==Examples==
 
==Examples==
 
===Example #1 bbcode_options===
 
===Example #1 bbcode_options===
This example uses the bbcode_options field which is used in forums and groups description parsing:
+
This example shows the "standard" option where BBCode, magic urls and smilies are allowed
<php>$sql = 'SELECT text, bbcode_uid, bbcode_bitfield, bbcode_options
+
<php>
    FROM ' . YOUR_TABLE . '
+
    WHERE some_id = ' . (int) $example_id;
+
$result = $db->sql_query($sql);
+
$row = $db->sql_fetchrow($result);
+
$db->sql_freeresult($result);
+
  
$text = generate_text_for_storage($row['text'], $row['bbcode_uid'], $row['bbcode_bitfield'], $row['bbcode_options']);
+
$errors = generate_text_for_storage($some_text, $new_uid, $new_bitfield, $bbcode_options, true, true, true);
  
$template->assign_vars(array(
+
if(sizeof($errors)){
    'TEXT'      => $text,
+
// Errors occured, show them to the user.
));</php><br>
+
// PARSE_ERRORS variable must be defined in the template
 +
$template->assign_vars(array(
 +
'PARSE_ERRORS'      => implode('<br>', $errors),
 +
));
 +
 
 +
}else{
 +
// No parse errors; save the text in my table
 +
$sql = 'INSERT INTO ' . YOUR_TABLE . ' ' . $db->sql_build_array('INSERT', array(
 +
'text' => $some_text,
 +
'uid' => $new_uid,
 +
'bitfield' => $new_bitfield);
 +
$db->sql_query($sql);
 +
}
 +
</php>
  
 
===Example #2 Individual bbcode_options===
 
===Example #2 Individual bbcode_options===

Revision as of 16:15, 2 November 2013

generate_text_for_storage –– Display custom parsed text on user-facing pages.

Description

  1.  string[] generate_text_for_storage(string &$text, string &$uid, string &$bitfield, int &$flags, bool $allow_bbcode = false, bool $allow_urls = false, bool $allow_smilies = false)

Grab data from the user, manipulate the input according to the parameters then it returns the information meant to be sent to the database
This function is located in the /includes/functions_content.php file.

Parameters

Parameter IN/OUT/INOUT Usage
text INOUT Text string with the original text that is replaced with the text to send to the database generate_text_for_storage.
uid OUT BBCode UID, a randomly generated unique identifier to mark the bbcodes identified by the first pass encoding (which uses regular expressions) so they can be replaced using the quicker str_replace in the second pass.
bitfield OUT Bit field containing the information which bbcode is used in the text so only the relavant ones need to be loaded from the database.

BBCode bitfield. Used if $flags set BBCode enabled.

flags OUT Integer flag containing the information whether bbcode, smilies and magic urls are enabled (OPTION_FLAG_BBCODE, OPTION_FLAG_SMILIES and OPTION_FLAG_LINKS). This integer is set according to the values in the last 3 parameters. Column names vary from table to table.
allow_bbcode IN Whether or not to allow BBCode in the text
allow_urls IN Whether or not to allow automatic urls in the text
allow_smilies IN Whether or not to allow smilies in the text

IN means that it expects information to be stored in the variable when the function is called (most common use of parameters)
OUT means that it will discard the information that is sent to the function and the variable is changed inside the function
INOUT means that the function will use the contents in the variable and it will also change those contents

Return Values

Returns an array of strings with the errors that occurred while parsing
Note that if there are no errors the array will be empty.

Examples

Example #1 bbcode_options

This example shows the "standard" option where BBCode, magic urls and smilies are allowed

$errors generate_text_for_storage($some_text$new_uid$new_bitfield$bbcode_optionstruetruetrue);

if(
sizeof($errors)){
    
// Errors occured, show them to the user.
    // PARSE_ERRORS variable must be defined in the template
    
$template->assign_vars(array(
        
'PARSE_ERRORS'      => implode('<br>'$errors),
    ));

}else{
    
// No parse errors; save the text in my table
    
$sql 'INSERT INTO ' YOUR_TABLE ' ' $db->sql_build_array('INSERT', array(
            
'text'        => $some_text,
            
'uid'        => $new_uid,
            
'bitfield'    => $new_bitfield);
        
$db->sql_query($sql);
}

Example #2 Individual bbcode_options

This example uses the enable_bbcode, enable_smilies and enable_magic_url flags which can be used instead of a single options field and is used in parsing posts (for example).

$sql 'SELECT text, bbcode_uid, bbcode_bitfield, enable_bbcode, enable_smilies, enable_magic_url
    FROM ' 
YOUR_TABLE '
    WHERE some_id = ' 
. (int) $example_id;
$result $db->sql_query($sql);
$row $db->sql_fetchrow($result);
$db->sql_freeresult($result);

// Add up the flag options...
$bbcode_options = (($row['enable_bbcode']) ? OPTION_FLAG_BBCODE 0) +
    ((
$row['enable_smilies']) ? OPTION_FLAG_SMILIES 0) + 
    ((
$row['enable_magic_url']) ? OPTION_FLAG_LINKS 0);

$template->assign_vars(array(
    
'TEXT'      => generate_text_for_storage($row['text'], $row['bbcode_uid'], $row['bbcode_bitfield'], $bbcode_options),
));

Example #3 Forums Table Real World Example

Real-world example of a query that could be performed on the forums table to display the forum description.

$sql 'SELECT forum_name, forum_desc, forum_desc_uid, forum_desc_bitfield, forum_desc_options
        FROM ' 
FORUMS_TABLE '
        WHERE forum_id = ' 
. (int) $forum_id;
$result $db->sql_query($sql);
$row $db->sql_fetchrow($result);
$db->sql_freeresult($result);

$template->assign_vars(array(
    
'FORUM_NAME'        => $row['forum_name'],
    
'FORUM_DESC'        => generate_text_for_storage($row['forum_desc'], $row['forum_desc_uid'], $row['forum_desc_bitfield'], $row['forum_desc_options']),
));

Notes

Option Text Flags

The OPTION_FLAG_* constants are defined as:
define('OPTION_FLAG_BBCODE', 1);
define('OPTION_FLAG_SMILIES', 2);
define('OPTION_FLAG_LINKS', 4);
Adding these constants together will result in all three options being enabled.

See Also