{"id":226,"date":"2011-04-28T11:06:09","date_gmt":"2011-04-28T16:06:09","guid":{"rendered":"http:\/\/xlinesoft.com\/blog\/?p=226"},"modified":"2026-08-16T12:05:33","modified_gmt":"2026-08-16T17:05:33","slug":"taming-the-beast-events-buttons-and-code-snippets","status":"publish","type":"post","link":"https:\/\/xlinesoft.com\/blog\/2011\/04\/28\/taming-the-beast-events-buttons-and-code-snippets\/","title":{"rendered":"PHPRunner Events, Buttons and Code Snippets: When to Use Each"},"content":{"rendered":"<p>PHPRunner gives you several ways to add custom logic to a generated application. The most common are events, custom buttons, View as: Custom and code snippets. They can sometimes solve the same problem, but each one is best suited to a different kind of task.<\/p>\n<p>The easiest way to choose is to ask three questions:<\/p>\n<ol>\n<li>What should trigger the code?<\/li>\n<li>Does the code run on the server, in the browser, or both?<\/li>\n<li>Is the change tied to a specific page action, or is it simply custom content that belongs on the page?<\/li>\n<\/ol>\n<table>\n<thead>\n<tr>\n<th>Method<\/th>\n<th>Best used for<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td>Events<\/td>\n<td>Code that runs automatically at a specific point in the application lifecycle<\/td>\n<\/tr>\n<tr>\n<td>Custom buttons<\/td>\n<td>Actions explicitly triggered by the user<\/td>\n<\/tr>\n<tr>\n<td>View as: Custom<\/td>\n<td>Changing how a field value is displayed<\/td>\n<\/tr>\n<tr>\n<td>Code snippets<\/td>\n<td>Adding dynamic server-generated content directly to a page<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>The server-side examples below use PHP and PHPRunner. In ASPRunner.NET, server-side event and snippet code is written in C#; the JavaScript examples use the same client-side approach.<\/p>\n<h2>Events<\/h2>\n<p>Use an event when code should run automatically at a defined point in the application lifecycle. Examples include validating or changing values before a record is saved, running code after a record is added, or changing page behavior when a page loads.<\/p>\n<p>See the <a href=\"https:\/\/xlinesoft.com\/phprunner\/docs\/events.htm\">PHPRunner Events documentation<\/a> or the <a href=\"https:\/\/xlinesoft.com\/asprunnernet\/docs\/events.htm\">ASPRunner.NET Events documentation<\/a>.<\/p>\n<h3>Server events<\/h3>\n<p>Typical server-side events can send email, check related records, modify data or perform other actions before or after a database operation.<\/p>\n<p><strong>Example 1: Send an email after a record is added<\/strong><\/p>\n<p>The following PHPRunner example uses <strong>runner_mail()<\/strong>:<\/p>\n<div class=\"my-syntax-highlighter\">\n<pre><textarea id=\"mshighlighter\" class=\"mshighlighter\" language=\"php\" name=\"mshighlighter\" >\r\n$email = \"test@test.com\";\r\n$from = \"admin@test.com\";\r\n$msg = \"Hello there\";\r\n$subject = \"Sample subject\";\r\n\r\n$ret = runner_mail(array(\r\n\t'to' => $email,\r\n\t'subject' => $subject,\r\n\t'body' => $msg,\r\n\t'from' => $from\r\n));\r\n\r\nif (!$ret[\"mailed\"])\r\n\techo $ret[\"message\"];<\/textarea><\/pre>\n<\/div>\n<p>See the <a href=\"https:\/\/xlinesoft.com\/phprunner\/docs\/runner_mail_function.htm\">runner_mail() documentation<\/a> for the available email parameters.<\/p>\n<p><strong>Example 2: Check for related Order Details before deleting an Order<\/strong><\/p>\n<p>Use the <strong>Before record deleted<\/strong> event. Instead of the old DAL API, use the current PHPRunner Database API:<\/p>\n<div class=\"my-syntax-highlighter\">\n<pre><textarea id=\"mshighlighter\" class=\"mshighlighter\" language=\"php\" name=\"mshighlighter\" >\r\n$rs = DB::Select(\r\n\t\"OrderDetails\",\r\n\tarray(\"OrderID\" => $deleted_values[\"OrderID\"])\r\n);\r\n\r\nif ($rs->fetchAssoc())\r\n{\r\n\t$message = \"This order has related Order Details records and cannot be deleted.\";\r\n\treturn false;\r\n}\r\n\r\nreturn true;<\/textarea><\/pre>\n<\/div>\n<p>The <strong>$deleted_values<\/strong> array contains values from the record being deleted.<\/p>\n<p>See <a href=\"https:\/\/xlinesoft.com\/phprunner\/docs\/before_record_deleted.htm\">Before record deleted<\/a> and the <a href=\"https:\/\/xlinesoft.com\/phprunner\/docs\/about_database_api.htm\">PHPRunner Database API<\/a>.<\/p>\n<h3>JavaScript OnLoad events<\/h3>\n<p>JavaScript OnLoad events are useful when you need to change controls or page behavior in the browser.<\/p>\n<p>For example, hide the State control unless Country is set to US:<\/p>\n<div class=\"my-syntax-highlighter\">\n<pre><textarea id=\"mshighlighter\" class=\"mshighlighter\" language=\"js\" name=\"mshighlighter\" >\r\nvar ctrlCountry = Runner.getControl(pageid, \"country\");\r\nvar ctrlState = Runner.getControl(pageid, \"state\");\r\n\r\nctrlCountry.on(\"change\", function(e) {\r\n\tif (this.getValue() == \"US\") {\r\n\t\tctrlState.show();\r\n\t} else {\r\n\t\tctrlState.hide();\r\n\t}\r\n});<\/textarea><\/pre>\n<\/div>\n<p>See the <a href=\"https:\/\/xlinesoft.com\/phprunner\/docs\/javascript_api.htm\">PHPRunner JavaScript API<\/a>.<\/p>\n<h3>How to choose the right event<\/h3>\n<p>Ask yourself two questions:<\/p>\n<p><strong>1. When should the code run?<\/strong><\/p>\n<p>Events run at specific points during page processing. For example, if something should happen after a new record is saved, use an AfterAdd event. If you need to prevent a record from being deleted, use BeforeDelete.<\/p>\n<p><strong>2. What data does the code need?<\/strong><\/p>\n<p>Each event provides a specific set of parameters. Choose an event that gives you access to the values and page information required by your code.<\/p>\n<h2>Custom buttons<\/h2>\n<p>Use a custom button when the user should explicitly trigger an action.<\/p>\n<p>A custom button can contain three parts:<\/p>\n<ul>\n<li><strong>Client Before<\/strong> &#8211; JavaScript that runs in the browser before the server action;<\/li>\n<li><strong>Server<\/strong> &#8211; PHP in PHPRunner or C# in ASPRunner.NET;<\/li>\n<li><strong>Client After<\/strong> &#8211; JavaScript that runs after the server action finishes.<\/li>\n<\/ul>\n<p>See the <a href=\"https:\/\/xlinesoft.com\/phprunner\/docs\/inserting_button.htm\">PHPRunner custom button documentation<\/a> or the <a href=\"https:\/\/xlinesoft.com\/asprunnernet\/docs\/inserting_button.htm\">ASPRunner.NET custom button documentation<\/a>.<\/p>\n<p><strong>Example 1: Email selected records<\/strong><\/p>\n<p>Add a custom button to the List page and put the following code in its Server event:<\/p>\n<div class=\"my-syntax-highlighter\">\n<pre><textarea id=\"mshighlighter\" class=\"mshighlighter\" language=\"php\" name=\"mshighlighter\" >\r\n$email_msg = \"List of records\\r\\n\\r\\n\";\r\n\r\nwhile ($record = $button->getNextSelectedRecord())\r\n{\r\n\t$email_msg .= \"OrderID: \" . $record[\"OrderID\"] . \"\\r\\n\";\r\n\t$email_msg .= \"CustomerID: \" . $record[\"CustomerID\"] . \"\\r\\n\";\r\n\t$email_msg .= \"\\r\\n\";\r\n}\r\n\r\n$email = \"test@test.com\";\r\n$subject = \"Selected records\";\r\n\r\n$ret = runner_mail(array(\r\n\t'to' => $email,\r\n\t'subject' => $subject,\r\n\t'body' => $email_msg\r\n));\r\n\r\nif (!$ret[\"mailed\"])\r\n\t$result[\"message\"] = $ret[\"message\"];<\/textarea><\/pre>\n<\/div>\n<p>The <strong>$button->getNextSelectedRecord()<\/strong> method gives the Server event access to the selected records without running a separate database query.<\/p>\n<p><strong>Example 2: Mark selected invoices as Paid<\/strong><\/p>\n<div class=\"my-syntax-highlighter\">\n<pre><textarea id=\"mshighlighter\" class=\"mshighlighter\" language=\"php\" name=\"mshighlighter\" >\r\nwhile ($record = $button->getNextSelectedRecord())\r\n{\r\n\t$data = array();\r\n\t$data[\"Status\"] = \"Paid\";\r\n\r\n\t$keyvalues = array();\r\n\t$keyvalues[\"InvoiceID\"] = $record[\"InvoiceID\"];\r\n\r\n\tDB::Update(\"Invoices\", $data, $keyvalues);\r\n}<\/textarea><\/pre>\n<\/div>\n<p>This example uses the current PHPRunner Database API instead of the old DAL or CustomQuery approach.<\/p>\n<h2>View as: Custom<\/h2>\n<p>Use <strong>View as: Custom<\/strong> when you want to modify how a field value is displayed on List, View, Print or Export pages.<\/p>\n<p>The current field value is available as <strong>$value<\/strong>. Other fields in the same record are available through <strong>$data[&#8220;FieldName&#8221;]<\/strong>.<\/p>\n<p>See the <a href=\"https:\/\/xlinesoft.com\/phprunner\/docs\/view_as_settings_custom.htm\">PHPRunner View as: Custom documentation<\/a>.<\/p>\n<p><strong>Example 1: Display LastName, FirstName<\/strong><\/p>\n<p>If the FirstName field is being formatted:<\/p>\n<div class=\"my-syntax-highlighter\">\n<pre><textarea id=\"mshighlighter\" class=\"mshighlighter\" language=\"php\" name=\"mshighlighter\" >\r\nif ($data[\"LastName\"])\r\n\t$value = $data[\"LastName\"] . \", \" . $value;<\/textarea><\/pre>\n<\/div>\n<p><strong>Example 2: Convert a value to uppercase<\/strong><\/p>\n<div class=\"my-syntax-highlighter\">\n<pre><textarea id=\"mshighlighter\" class=\"mshighlighter\" language=\"php\" name=\"mshighlighter\" >\r\n$value = strtoupper($value);<\/textarea><\/pre>\n<\/div>\n<p><strong>Example 3: Format a 10-digit phone number<\/strong><\/p>\n<div class=\"my-syntax-highlighter\">\n<pre><textarea id=\"mshighlighter\" class=\"mshighlighter\" language=\"php\" name=\"mshighlighter\" >\r\nif (strlen($value) == 10)\r\n{\r\n\t$value = \"(\" .\r\n\t\tsubstr($value, 0, 3) .\r\n\t\t\") \" .\r\n\t\tsubstr($value, 3, 3) .\r\n\t\t\"-\" .\r\n\t\tsubstr($value, 6);\r\n}<\/textarea><\/pre>\n<\/div>\n<h2>Code snippets<\/h2>\n<p>Use a code snippet when you want to place dynamic server-generated content directly on a page.<\/p>\n<p>In PHPRunner, code snippets contain PHP. In ASPRunner.NET, they contain C# or VB.NET; for new ASPRunner.NET examples we use C#.<\/p>\n<p>See the <a href=\"https:\/\/xlinesoft.com\/phprunner\/docs\/insert_code_snippet.htm\">PHPRunner Code Snippet documentation<\/a> or the <a href=\"https:\/\/xlinesoft.com\/asprunnernet\/docs\/insert_code_snippet.htm\">ASPRunner.NET Code Snippet documentation<\/a>.<\/p>\n<p><strong>Example 1: Display the current time in PHPRunner<\/strong><\/p>\n<div class=\"my-syntax-highlighter\">\n<pre><textarea id=\"mshighlighter\" class=\"mshighlighter\" language=\"php\" name=\"mshighlighter\" >\r\necho date(\"Y-m-d H:i:s\");<\/textarea><\/pre>\n<\/div>\n<p>The corresponding ASPRunner.NET C# snippet can use:<\/p>\n<p>[csharp]<br \/>\nMVCFunctions.Echo(MVCFunctions.now());<br \/>\n[\/csharp]<\/p>\n<p><strong>Example 2: Display values retrieved from the database<\/strong><\/p>\n<p>For example, display a list of orders for a customer:<\/p>\n<div class=\"my-syntax-highlighter\">\n<pre><textarea id=\"mshighlighter\" class=\"mshighlighter\" language=\"php\" name=\"mshighlighter\" >\r\n$customerID = \"ALFKI\";\r\n\r\n$rs = DB::Select(\r\n\t\"Orders\",\r\n\tarray(\"CustomerID\" => $customerID),\r\n\tarray(\"OrderID\")\r\n);\r\n\r\nwhile ($data = $rs->fetchAssoc())\r\n{\r\n\techo \"Order \" . $data[\"OrderID\"] . \" - \" . $data[\"OrderDate\"] . \"<br>\";\r\n}<\/textarea><\/pre>\n<\/div>\n<h3>Passing page data to a code snippet<\/h3>\n<p>Sometimes a code snippet needs a field value from the current View or Edit record.<\/p>\n<p>One option is to save the record values to a session variable in the page&#8217;s <strong>Process Record Values<\/strong> event:<\/p>\n<div class=\"my-syntax-highlighter\">\n<pre><textarea id=\"mshighlighter\" class=\"mshighlighter\" language=\"php\" name=\"mshighlighter\" >\r\n$_SESSION[\"currentRecord\"] = $values;<\/textarea><\/pre>\n<\/div>\n<p>The code snippet can then use those values:<\/p>\n<div class=\"my-syntax-highlighter\">\n<pre><textarea id=\"mshighlighter\" class=\"mshighlighter\" language=\"php\" name=\"mshighlighter\" >\r\nif (isset($_SESSION[\"currentRecord\"][\"Make\"]))\r\n\techo \"Make: \" . $_SESSION[\"currentRecord\"][\"Make\"];<\/textarea><\/pre>\n<\/div>\n<p>The ASPRunner.NET manual documents the same pattern using C# and <strong>XSession.Session<\/strong>.<\/p>\n<h2>Which one should you use?<\/h2>\n<p>A useful rule is to start with the extension point that most closely matches the action:<\/p>\n<ul>\n<li>If something should happen automatically while a page or record is being processed, use an <strong>event<\/strong>.<\/li>\n<li>If the user should click something to start the action, use a <strong>custom button<\/strong>.<\/li>\n<li>If you only need to change how a field value appears, use <strong>View as: Custom<\/strong>.<\/li>\n<li>If you need a small piece of dynamic server-generated content on the page, use a <strong>code snippet<\/strong>.<\/li>\n<\/ul>\n<p>For database work in new code, use the <a href=\"https:\/\/xlinesoft.com\/phprunner\/docs\/about_database_api.htm\">PHPRunner Database API<\/a> or the <a href=\"https:\/\/xlinesoft.com\/asprunnernet\/docs\/about_database_api.htm\">ASPRunner.NET Database API<\/a> rather than the legacy DAL API.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>PHPRunner gives you several ways to add custom logic to a generated application. The most common are events, custom buttons, View as: Custom and code snippets. They can sometimes solve the same problem, but each one is best suited to a different kind of task. The easiest way to choose is to ask three questions: What should trigger the code? Does the code run on the server, in the browser, or both? Is the change tied to a specific page action, or is it simply&#8230;<span class=\"clearfix clearfix-post\"><\/span><a href=\"https:\/\/xlinesoft.com\/blog\/2011\/04\/28\/taming-the-beast-events-buttons-and-code-snippets\/\" class=\"more-link\">Continue Reading <span class=\"screen-reader-text\">&#8220;PHPRunner Events, Buttons and Code Snippets: When to Use Each&#8221;<\/span> <span class=\"meta-nav\">&rarr;<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1,4,8],"tags":[],"class_list":["post-226","post","type-post","status-publish","format-standard","hentry","category-php-category","category-php-code-generator","category-tutorials"],"_links":{"self":[{"href":"https:\/\/xlinesoft.com\/blog\/wp-json\/wp\/v2\/posts\/226","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/xlinesoft.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/xlinesoft.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/xlinesoft.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/xlinesoft.com\/blog\/wp-json\/wp\/v2\/comments?post=226"}],"version-history":[{"count":18,"href":"https:\/\/xlinesoft.com\/blog\/wp-json\/wp\/v2\/posts\/226\/revisions"}],"predecessor-version":[{"id":3439,"href":"https:\/\/xlinesoft.com\/blog\/wp-json\/wp\/v2\/posts\/226\/revisions\/3439"}],"wp:attachment":[{"href":"https:\/\/xlinesoft.com\/blog\/wp-json\/wp\/v2\/media?parent=226"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/xlinesoft.com\/blog\/wp-json\/wp\/v2\/categories?post=226"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/xlinesoft.com\/blog\/wp-json\/wp\/v2\/tags?post=226"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}