Scripting for the Rest of Us, Lessons with Video

We hear things like this every day: "xTuple's scripting environment is such a powerful tool." and "I just wanted to give the dev team and all contributors a kudos for making such a solid and mold-able product." Thanks to a member of our community, you can start building your own xTuple Scripting ToolBox today. Avoid beating your head against the wall as you attempt to leverage the flexibility of open source software and accomplish some scripting to custom fit xTuple for your specific needs.

Updated from original post: March 29, 2016

Start Building Your xTuple Scripting ToolBox Today

This is a series of articles to give you the skills — and confidence — necessary to modify and extend the out-of-the-box xTuple ERP software. Thanks to the flexibility of open source software, you can tailor the World’s #1 Open Source ERP package into a custom fit for your company and/or customer.

What is scripting?

verb | \’skripting\ — to write an executable section of computer code

xTuple Scripting: Lesson 1

Dipping your toe(s) in the water

First, we will go over the goals of the entire series, laying out the specific skills (referred to as “Learning Tasks”) that will be mastered over the entire series. Two specific learning skills will be mastered in this lesson. Each lesson builds on the previous lesson and requires the skills learned in all previous lessons.

For those of you that don’t consider yourselves "professional programmers" even the definition of scripting seems daunting. However, as this series of articles will prove to you, it is not as daunting as one might initially suspect.

Before we start: a disclaimer — I am not, nor do I pretend to be, an expert in xTuple Scripting. Nothing could be further from the truth. Actually, truth be told, I’m a ‘newbie’ to it. While I’ve been writing code, professionally, for over three (3) decades there are more fingers on your two hands than there are calendar months of experience that I can lay claim to when it comes to xTuple scripting. “So,” you might ask, “where do you get off writing a series of articles purporting to show me how to create xTuple scripts?” My response would be: “Great Question” as I then slink away with my tail between my legs.

Okay. Maybe not. My REAL response would be “I had to beat my head against the walls until there were not only big dents in the wall but blood red stains embedded within those dents as I tried to figure out how to do things that I considered fairly basic and simple. So the plain and simple answer to your question is that I would like to help you avoid that head-banging and provide you with an xTuple script that 1) you’ll understand when we’re all done and 2) you can use as a template to branch off and start doing your own thing.”

Bottom line: If you are already creating your own xTuple scripts and know what you’re doing read no further. You are WAY ahead of me. On the other hand, if you’ve not written any scripts, or been frustrated TRYING to write scripts, READ ON!

So here is how this is going to work: I have invented a mythical xTuple end-user (let’s call him Bubba) who has made some fairly simple requests of features/functions that he wants added to his xTuple system. Over this series of articles we will slowly build up xTuple script(s) to handle each and every one of Bubba’s requests. We’re going to do this slowly. Painfully slow. The purpose for this turtle pace is to make sure you understand EACH AND EVERY STEP we take — so you can use that particular step on your own to accomplish your own needs. Finally, I can’t guarantee how fast I’ll get these articles written. I DO have my normal job/work to deal with. So these articles will trickle in as I have the time.

So let’s get going. Here is Bubba’s request/wish list:

1. Add a new field to the Customer Settings Tab.
1. This field should be to the right of the Shipping Charges field
2. The field should be named “New Field”
3. The field should allow unlimited alpha-numeric entry
4. The field data should be saved to the xTuple database
5. The field should behave as any other field on the Customer panel and be saved, retrieved, and updated as needed, when editing/viewing the customer record
6. If there is data in any particular customer’s “New Field” then pop-up a panel showing the end user who the sales rep is for this customer BEFORE showing any other customer data
1. If there isn’t data in a particular customer’s “New Field” then simply proceed onto the normal Customer panel
2. Add a new Button, also on the Customer Settings Tab.
1. The button should be named “Edit Sales Rep Info”
2. When the button is pressed, the standard Sales Rep panel for this Customer’s sales rep should appear for editing or viewing
3. The panel should follow the SALES module privilege of MAINTAINSALESREPS
1. If the user has the privilege, they should be able to edit the sales rep information when the panel pops up
2. If the user doesn’t have the privilege, they should only be able to view the sales rep information when the panel pops up
3. Add a 2nd new button, also on the Customer Settings Tab.
1. The button should be named “Site Items”
2. When the button is pressed, the end user should see a list of all the items maintained at the default warehouse
3. The end user should be able to change the warehouse to other than the default
4. The end user should be able to select an item, within a warehouse, and view the standard Item panel
5. The end user should be able to select an item, within a warehouse, and view the standard Item Site panel

That’s it. Those three (3) items are ALL that Bubba wants done. But let me tell you...that is actually a huge list when you consider the things that you need to do "behind the scenes."

Let’s just enumerate what we’re going to accomplish if we satisfy all of Bubba’s three (3) wishes. You will learn how to:

1. Override a standard xTuple panel so that you can modify it.
2. Add a field to a standard xTuple panel, and place that field where you want it on the panel.
3. Make a new schema in the xTuple database.
4. Create a new table, within your new schema, in the xTuple database.
5. Create this table, on the fly, so once your scripting is installed the necessary schema and table will be built, automatically, by your script.
6. Add buttons to a standard xTuple panel.
7. Respond to your new button(s) being pressed and then “do” whatever those buttons were intended to do.
8. Call standard xTuple panels and screens and present them to the user under control of your script.
9. Call non-standard (custom) panels and screens (that you probably built) and present them to the user under control of your script.
10. Present important messages/information to the user as your custom scripting is executing.
11. Write your scripting into multiple scripts (to keep them clean and organized) and then how to include the scripts so they execute as a "whole." This is so you don’t just write one long, hard-to-comprehend, script.
12. Override an existing button, to allow whatever work you need done to be accomplished, and then allow the button’s normal behavior to continue on. (An example of this is if you need something done when the user presses an existing SAVE button)
13. Make a decision, within your script, based on the data in a field and then perform, or not perform, some action based on that data.
14. Trap errors, report them to your end user AND log these errors into the main database log for viewing at a later time.
15. AND MOST IMPORTANTLY: YOU WILL LEARN NOT TO BE AFRAID OF XTUPLE SCRIPTING.

Oh yeah. That’s a whole bunch of learning. If you read through that list carefully, you’ll discover that MOST of what you would need to do for yourself, or some customer, is somewhere in that list. Add buttons. Make those buttons do useful tasks. Add fields. Add that field data to the xTuple database. Pop up existing panels. Pop up custom panels. Display messages. Make decisions based on data. Not to mention some of the resources you’ll learn how to access, and refer to, as this project moves along.

So without further ado...let’s start scripting.

Today we will accomplish

• Learning Task #1 — How to override a standard xTuple panel so you can modify it
• Learning Task #10 — How to present important message/information to the user as your custom scripting is executing

Since a picture is worth 1,000 words, you can view this article’s lesson online. Additionally, you’ll be able to view the finished product, with all of Bubba’s modifications created and functioning. This will let you see what YOU will be building as you progress thru the various lessons of this xTuple Scripting tour. 

xTuple Scripting Lesson 1

xTuple Scripting Lesson 2

What scripting have you done?

Post your comments, questions and suggest solutions here: xTuple Forums: Current functionality.

Photo credit: Jessica/goaliej54 on Flickr