PHPRunner Events, Buttons and Code Snippets: When to Use Each
PHP, PHP Code Generator, TutorialsPHPRunner 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 custom content that belongs on the page?
| Method | Best used for |
|---|---|
| Events | Code that runs automatically at a specific point in the application lifecycle |
| Custom buttons | Actions explicitly triggered by the user |
| View as: Custom | Changing how a field value is displayed |
| Code snippets | Adding dynamic server-generated content directly to a page |
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.
Events
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.
See the PHPRunner Events documentation or the ASPRunner.NET Events documentation.
Server events
Typical server-side events can send email, check related records, modify data or perform other actions before or after a database operation.
Example 1: Send an email after a record is added
The following PHPRunner example uses runner_mail():
See the runner_mail() documentation for the available email parameters.
Example 2: Check for related Order Details before deleting an Order
Use the Before record deleted event. Instead of the old DAL API, use the current PHPRunner Database API:
The $deleted_values array contains values from the record being deleted.
See Before record deleted and the PHPRunner Database API.
JavaScript OnLoad events
JavaScript OnLoad events are useful when you need to change controls or page behavior in the browser.
For example, hide the State control unless Country is set to US:
See the PHPRunner JavaScript API.
How to choose the right event
Ask yourself two questions:
1. When should the code run?
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.
2. What data does the code need?
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.
Custom buttons
Use a custom button when the user should explicitly trigger an action.
A custom button can contain three parts:
- Client Before – JavaScript that runs in the browser before the server action;
- Server – PHP in PHPRunner or C# in ASPRunner.NET;
- Client After – JavaScript that runs after the server action finishes.
See the PHPRunner custom button documentation or the ASPRunner.NET custom button documentation.
Example 1: Email selected records
Add a custom button to the List page and put the following code in its Server event:
The $button->getNextSelectedRecord() method gives the Server event access to the selected records without running a separate database query.
Example 2: Mark selected invoices as Paid
This example uses the current PHPRunner Database API instead of the old DAL or CustomQuery approach.
View as: Custom
Use View as: Custom when you want to modify how a field value is displayed on List, View, Print or Export pages.
The current field value is available as $value. Other fields in the same record are available through $data[“FieldName”].
See the PHPRunner View as: Custom documentation.
Example 1: Display LastName, FirstName
If the FirstName field is being formatted:
Example 2: Convert a value to uppercase
Example 3: Format a 10-digit phone number
Code snippets
Use a code snippet when you want to place dynamic server-generated content directly on a page.
In PHPRunner, code snippets contain PHP. In ASPRunner.NET, they contain C# or VB.NET; for new ASPRunner.NET examples we use C#.
See the PHPRunner Code Snippet documentation or the ASPRunner.NET Code Snippet documentation.
Example 1: Display the current time in PHPRunner
The corresponding ASPRunner.NET C# snippet can use:
[csharp]
MVCFunctions.Echo(MVCFunctions.now());
[/csharp]
Example 2: Display values retrieved from the database
For example, display a list of orders for a customer:
Passing page data to a code snippet
Sometimes a code snippet needs a field value from the current View or Edit record.
One option is to save the record values to a session variable in the page’s Process Record Values event:
The code snippet can then use those values:
The ASPRunner.NET manual documents the same pattern using C# and XSession.Session.
Which one should you use?
A useful rule is to start with the extension point that most closely matches the action:
- If something should happen automatically while a page or record is being processed, use an event.
- If the user should click something to start the action, use a custom button.
- If you only need to change how a field value appears, use View as: Custom.
- If you need a small piece of dynamic server-generated content on the page, use a code snippet.
For database work in new code, use the PHPRunner Database API or the ASPRunner.NET Database API rather than the legacy DAL API.
I have run to the end of my 90 days of support but would love to find someone that can teach me how to do these nifty things. I am definitely one of your users that is new to php but doing really powerful things with phprunner. Is there any kind of class that can be taken to teach us how to use the really great features that you have put into this program, even when we don’t know php all that well? That would be my wish.
1) great to see this kind of tutorial. I would like to see live examples using the codes suggested
2) test was good but perhaps a little long. 10 questions max for my attention span!
3)I would pay $25 no problem. This is a great looking template and hope phprunner6.0 will be this good looking. I do get comments that 5.3 and previous look dated which I guess is why the big overhaul in 6.0.
I think more purchasable templates would be good but the user needs to be able to customise easily. I struggle to get calendar template to do what I want as there is much tricky code that I dont understand the implications of.
That’s all – keep up the good work
Gareth
I think you are on the right track and I really appreciate the effort you are making. I loved the idea of allowing users to post their own tips, tricks, and know-how also. Like the previous comment, I struggled for days before I finally got the calendar program to do what I wanted, mainly with the permission levels to view different schedules. It would be nice for us to be able to share those tips if that would not violate any of your copyright notices. Maybe you could have the site set up where you could review the tips before posting them. One site I go to has a special area for code only supported mostly by end users. Your skill level is obviously way above the average user and thus, difficult to bring down to most users level. I will check out your quiz program soon. Thanks! Keep on Developing! LarryM
This is it. If you want to check how well you understand the difference between those methods take a quick RunnerIQ test. This test was built by PHPRunner btw.
Would love to see a tutorial on how the RunnerIQ test quiz was build using PHPRunner.
Nice test – nice functionality – not overly fancy but yet clean and functional. Question count maybe a tad high – some questions were not relevant in this tutorial so I had a few mistakes [sigh] :-). If I had a need for such a template, I’d pay 10-25 dollars for it. I think if you keep making these tutorials (which is a good thing), then such a test to go with it is good as it helps with retention of the info. All in all, I recall my first use of phprunner – there were so many little tricks and techniques that you had to sift through the forums to find, to get advanced things done. Very capable product, hence the need for these tutorials and good documentation to get these tips/tricks in front of the users. I had found that if you get into modifying the templates, you can really unleash power and do most anything (not that that is easy – to varying degrees). That recent article about the Book idea and post by electro rick was really insightful with excellent points et al. I am looking forward to the v6 generation…
This is a wonderful tutorial for the various custom actions which can be done using the application.
RunnerIQ test is also wonderful. I would wish to purchase the same for $1.
Nice tutorial. Most of this info exists elsewhere, but it’s nice to pull it together like this and point out specific things. More real examples (as mentioned by others) would be good. As a note: I am a lazy programmer (which is why I love your product – it does it for me!) so the more you can make this kind of advanced funcionality available via GUI selections in the app the better.
Sharing tips and tricks between users is a good idea too. Also, “expert app reviewers” would be cool. Like: I create an app but want to run it by someone else and get thoughs about the approach – is it the best way to accomplish the task. Would people pay for that? Is that a good idea?… I don’t know, just having that thought now.
Test was nice use of Runner. Maybe less quetions would be better.
Thanks for your great product!
I really like you taking an interest in helping your customers with coding snippets. I have written many, and they really help.
I feel .. The examples need more comments to describe the coding flow.
I like to write in “The Kings English”. I have been very successful with this technique. Would be nice if the variables were a little more descriptive and the coding, i.e. using “The King’s English” .. no so cryptic. If I were to use your code I would completely restructure it for flow and readability. (Someone besides me may have to debug it)
I cannot say enough about PhpRunner. It got me out of a MAJOR jam. I have been a fan ever since.
I feel that customers that renew their yearly license should be able to use these snippets w/o charge. Now … feature enhancements / skins etc. .. another story.
Take Care,
Peter
Hello Serjey,
Greetings ! Well Done.
I had a query which I am waiting since several years to come. I think I had put it several times over the forum. I had compared several products with phprunner. the best example is sqlmaestro php generator. Of course every product has its pros and cons so this is not in an effort to compare both, but I would like to add a facility which will just enhance this product to new levels which cannot be imagined by anyone. The query goes below:-
In a master detail form, I had requested that every field in the master detail form should be able to give reference of the same in a sql query. I mean that we should be able to give a simple sql in the column name to populate values based on any field (master or detail)
like for example I have a master column customerid and when i am in detail form I want orders displayed only of the customer id selected in the master table the sql may be simple looking as below
select orderno from ordermst where customerid = :masterform.customerid
Now here I am in detail record here.
Every user is not that familiar with php to write the above complicated codes you have given. Of course it is in good and intelligent effort of yours, but it does not satisfy the user needs. My head started turning after looking at that code. So request to declare a simple variable by default for every column of the table by default and allow it to be referred in any sql given for any column. If this is done I think phprunner will never look back. I wish you all the best.
And btw, This is the only major constraint I had found in phprunner since last 2 years. I had been observing this at very close context.
Many thanks Sergey for your effort to compile this tutorial.
Further topics for new tutorials could be:
• Handling of variables, that is are not stored in database e.g. variables for user communication, preparing questions to user as in the RunnersIQ Test and to get user’s decisions like “would you prefer to do this or that”, based on findings of DB querys and application logic.
• Understanding events, what can be done at the various steps of the lifetime of a query, what information is available etc. I wasted a lot of time to find out that an operation is not possible eg. working at a list item.
The RunnerIQ Test is too long, I canceled it half way.
I would pay for the template 25 $.
Thanks for you fabulous approach to support and customer information.
Best Regards
Ulrich Lüer
UL.Consult GmbH
I like the tutorial, but have a suggestion.
Where listing the snippets in PHP, could you also put the equivalent in ASP? That would be tremendously helpful.
I think that this should just be built into the purchase price of PHPRunner
The quiz template is a good idea. However, for it to be a complete system, there should be an admin side for creating quizes via the web and running reports.
Maurice,
Quiz template is a complete system. It allows you to create new quizzes via web, add reports and charts etc.