How to pre-populate a new record with data passed through the url?

In some cases, you might have frequent data entries with some common values. This can be made faster and more efficient using specially formatted shortcut links.

For example, an inventory officer might be doing a lot of data entries all day for some frequent transactions: maybe lots of printing paper packs are withdrawn from inventory all day ... so a link labeled Printing paper out that would populate a new inventory transaction with type out, item Printing paper and a quantity of 1 would save many keystrokes and make our officer happier :)

In fact, if our inventory officer has 100 such entries per day, crafting a link to save her from typing the above values over and over, would cut around 1 hour of tedious boring work!

Referring to the AppGini URL parameters page, we can see that, for a table named inventory, the inventory table view page url is inventory_view.php. If we append the parameter addNew_x=1 to the url, it would open the inventory new form page, inventory_view.php?addNew_x=1.

The above trick would save our officer from having to first open the inventory table view, then clicking Add new. That's a good start already! But let's save more time and effort by modifying this url so it pre-populates the form with values frequently used.

What we want to do is have our officer open a url such as:

inventory_view.php?addNew_x=1&item=Printing+paper&type=out&quantity=1

and have the new entry form pre-filled with the item box set to Printing paper, the transaction type box set to out and the quantity box set to 1.

This involves 2 main steps:

  1. Placing the link somewhere easily accessible in our app.
  2. Adding code for handling the link (pre-filling the new entry form).

To add the link to the homepage of our AppGini app, open the generated hooks/links-home.php file in a text editor, and add the following code to it:

$homeLinks[] = [
  'url' => 'inventory_view.php?addNew_x=1&item=Printing+paper&type=out&quantity=1', 
  'title' => 'Printing paper out', 
  'table_group' => 'Operations',
];

The value of the url in line 2 above should follow this pattern:

{table name}_view.php?addNew_x=1&{field name}={value}&{field name}={value}...

And the table_group value should be set to the name of the table group you'd like to place the link in. The above code should display the link like this:

You could also/instead add the link to the navigation menu. To do so, add this code to the generated hooks/links-navmenu.php:

$navLinks[] = [
  'url' => 'inventory_view.php?addNew_x=1&item=Printing+paper&type=out&quantity=1', 
  'title' => 'Printing paper out', 
  'table_group' => 1,
];

You might notice the similarity between this piece of code and the previous one. The differences are using $navLinks instead of $homeLinks, and using the table group index (1 in the above example, line 4) rather than name.

TIP! You can repeat the code above as many times as you wish to place multiple links in the homepage or the navigation menu.

Now that the link is placed in our app, all we need to do is add a little piece of code for handling it and pre-filling the new entry form. In the hooks folder, create a file named inventory-dv.js if it doesn't already exist (replace inventory by the actual table name in your case). Add this code to it:

$j(() => {
  // get url
  const url = new URL(location.href);

  // if not insert mode, triggered by GET, abort
  if(!url.searchParams.get('addNew_x')) return;

  // for every parameter, try to populate corresponding form element
  url.searchParams.forEach((val, key) => {
      const el = $j(`#${key}`);
    if(!el.length == 1) return;
    
    el.val(val);
  })
})

Now, whenever the link is clicked, the new entry form is displayed, pre-filled with the values that we pass via the url.

One caveat in the above code is that it works only with text and text area fields. It won't work for drop-downs, dates or other field types. We'll try to post an update to this article later on to support those types of fields.