There is a new version of our single-click packager for AppGini projects.

Download here and check it out.

If you don't already have a license, have a look at the product page here.

There is a new Simulation mode which generates a list of packed files instead of creating a new package. So you can check what will be inside before.

Adding buttons and adding links to a table view has been described in the docs. By using the %ID% placeholer you can use the record's primary key as parameter for links. For example for opening the record in detail view. In this article we are going to use the %ID% parameter for adding a sub-item (child record / detail record) to the row.

The Online Clinical Management System (OCMS), which I'm using in many examples, contains patients and appointments. Appointments are stored in a table named events. And the column name_patient has been configured as lookup field refering patients table.

Step 1: Button for opening details

Let's get started with adding a link (button) to patients table view for opening up one patient detail view record.

The URL-pattern (address) for a detail view record is
TABLENAME_view.php?SelectedID=THE_RECORDS_PRIMARY_KEY.

Example:
The URL for opening the detail view of patients table for record #1
patients_view.php?SelectedID=1.

If we know the URL, we can add a button to table view.

Create (or edit) a hooks file file table view named hooks/TABLENAME-tv.js (replace TABLENAME by the name of your specific table).

// file: hooks/patients-tv.js
jQuery(function () {

	var tv = new AppGiniTableView();

	// additional buttons for table view
	// add "open" button
	var tablename = AppGini.currentTableName();
	var url_open = tablename + "_view.php?SelectedID=%ID%";
	tv.addLink(url_open, "pencil", "", Variation.primary);

});

The screenshot show the result: The blue "pencil" buttons have been added to table view. A click opens up the detail view of that record.

Step 2: Create button for adding an appointment

Finding the URL for adding a subitem is a bit difficult. But don't worry: I will guide you. By using special parameters we can tell AppGini to open up the "Add new record" view for a table. The required parameter is addNew_x.

URL for adding new record to events table:

events_view.php?addNew_x=1

Note the ? character which separates the page (events_view.php) from one or more parameters.

Additionally we can pass default values to the view by using filterer_COLUMNNAME parameters.

In this case we need to pass the patient's primary key (value of patients.id) as default value for the new event's foreign key (column events.patient_name).

URL for adding a new event record as subitem refering patient #1:

events_view.php?addNew_x=1&filterer_name_patient=1

Note the & character for concatenating additional parameters. Also note that filterer_name_patient matches the syntax of filterer_COLUMNNAME, because our foreign key column name is name_patient.

You might wonder: The primary key of the master record (patient) changes from row to row. It is not a static value like 1 as we have seen in the example above. So, the question is: how can we pass the primary key for each individual patient-record?

We can use the placeholder %ID% to pass in the primary key of our patients table row by row.

events_view.php?addNew_x=1&filterer_name_patient=%ID%

Now we have our URL. So we can add a new button to our table view. In the following code I'm using a couple of variables to make the code easier to read, understand and copy/paste for you.

var details_table_name = "events";
var details_fk_column_name = "name_patient";
var url_add_detail = details_table_name + "_view.php?addNew_x=1&filterer_" + details_fk_column_name + "=%ID%";
tv.addLink(url_add_detail, "calendar", "+");

Full source code:

jQuery(function () {

	var tv = new AppGiniTableView();

	// additional buttons for table view
	// add "open" button
	var tablename = AppGini.currentTableName();
	var url_open = tablename + "_view.php?SelectedID=%ID%";
	tv.addLink(url_open, "pencil", "", Variation.primary);

	// add "add appointment" button
	var details_table_name = "events";
	var details_fk_column_name = "name_patient";
	var url_add_detail = details_table_name + "_view.php?addNew_x=1&filterer_" + details_fk_column_name + "=%ID%";
	tv.addLink(url_add_detail, "calendar", "+");
});

Result

On click, our button opens up the "Add-New Event" form with a predefined relation to this patient (Miller, Michael in this case):

As you can see, we are in "add new" mode of events-table. The default value for the (parent) patient has been set correctly. This gives many, many options for your projects.

Full short code with one additional button for listing all appointments of a patient:

// file: hooks/patients-tv.js
jQuery(function () {

	var tv = new AppGiniTableView();

	// additional buttons for table view
	// add "open" button
	var tablename = AppGini.currentTableName();
	var url_open = tablename + "_view.php?SelectedID=%ID%";
	tv.addLink(url_open, "pencil", "", Variation.primary);

	// add "list all appointsments of patient" button
	var url_appointments = "events_view.php?filterer_name_patient=%ID%";
	tv.addLink(url_appointments, "calendar");
	
	// add "add appointment" button
	var url_add_detail = "events_view.php?addNew_x=1&filterer_name_patient=%ID%";
	tv.addLink(url_add_detail, "calendar", "+");
});

Hope you like it. If you like it, please follow or like us on twitter and share this piece of information.

With Batch Actions you can execute a javascript function for all selected rows in a Table View. In this step-by-step guide I am going to show, how add a button to every table view row and execute an existing batch action on button click for that specific row.

The following video show the possibilities you have with Batch Actions and additional buttons per row:

Illustration

If you already have a working batch action script integrated in your TABLENAME-tv.js file, you can skip steps 1 and 2 and directly head over to step 3.

Step 1: Create Batch Action javascript function

If you don't already have it, create a file hooks/TABLENAME-tv.js and write your javascript function. Replace TABLENAME by your specific table name.

Please note the suffix -tv which stand for "table view".

// file: hooks/TABLENAME-tv.js
//                       ^
//                       +--- attention: tv = tableview
// the batch function itself
// two parameters: 
// 1. tablename
// 2. array of primary keys
function myBatchAction1(tn, ids) {

    // just show an alert box with tablename and selected primary keys
    alert("Table: " + tn + "\r\n" + "Selected IDs: " + ids);

}

Save the javascript file.

Step 2: Add function-call to the Batch Actions menu

For integrating this Batch Action javascript function into the Batch Actions menu, open the file hooks/TABLENAME.php and find the function named TABLENAME_batch_actions(). Usually this is the last function at the very bottom of the hooks file.

For the new Batch Action, add a definition to the array which will be returned by the function. Replace TABLENAME by your specific table name.

function TABLENAME_batch_actions(&$args)
{
	return [
		[
			"title" => "Show alert for selected rows",
			"function" => "myBatchAction1",
			"icon" => "flash"
		]
	];
}

Save the php file.

For every Batch Action you will need three parameters:

1. title
   This will become the menu item title
2. Name of the function
   This has to exactly match with the function name given in step 1. Use identical character casing.
   I recommend naming functions in camelCase.
3. Name of the (Glyph-) icon without glyphicon- prefix
   If the icon's name is glyphicon-flash, just put flash as icon name.

At this step we have created a javascript function named myBatchAction1 and integrated it as Batch Action into the menu. We can test it now:

1. Reload the table view page in your browser
   Please note: Depending on your permissions, the menu button may not be visible, yet
2. Select one or more rows by checking checkboxes in first column
   If the menu button has not been visible at page load, it will appear as soon as you have selected at least one row.
3. The Batch Actions menu should contain your new menu item now.
4. Click it
5. Your function will be executed and an alert box should show your table's name and the primary key(s) of the selected record(s)

These were the important two steps for creating Batch Actions according to the AppGini documentation.

In the last step we are going to use the addButton function of AppGini Helper Javascript Library to add a new button in every row and bind the click-event to our already coded javascript function.

Step 3: Add button to every row and call Batch Action javascript function

Once again, open hooks/TABLENAME-tv.js (replace TABLENAME) and add the following code which automagically adds a new button to every row of your table view:

// add a button per table row
jQuery(function () {

    new AppGiniTableView().addButton(function (id) {
        // call our function, pass tablename and the (=one) primary key
        myBatchAction1('TABLENAME', id);
    }, "flash", "Show alert for row");

});

As first parameter of .addButton(fx)-function we pass in a function call. Later on, on click, our library will execute that fx-function and pass the primary key of the specific record into that function. Inside our fx-function itself, we can use the passed in id as variable.

In this case, within fx, we execute our function myBatchAction1.

Remember:
Our Batch Action function myBatchAction1 requires two parameters: Tablename and primary key(s) of selected records. So we also have to pass in those two parameters. That's why we execute myBatchAction1('TABLENAME', id);

After step 2 we were able to execute our function for one or multiple selected records. Now, after step 3, we additionally (!) have a button per row and we can execute the same function per row.

That's it. You finally made it.

Pro-Tip

If you pass in 'TABLENAME' to the function, you will have to change the code whenever you rename the table. You can avoid this by using the built-in function AppGini.currentTableName() which returns the actual name of the current table view:

 // get the name of the current table
var tn = AppGini.currentTableName()

// call our function, pass tablename and the (=one) primary key
myBatchAction1(tn, id);

The whole optimized code of hooks/TABLENAME-tv.js:

// ...

function TABLENAME_batch_actions(&$args)
{
	return [
		[
			"title" => "Show alert for selected rows",
			"function" => "myBatchAction1",
			"icon" => "flash"
		]
	];
}

function myBatchAction1(tn, ids) {
    // just show an alert box with tablename and selected primary keys
    alert("Table: " + tn + "\r\n" + "Selected IDs: " + ids);
}

// add a button per table row
jQuery(function () {

    new AppGiniTableView().addButton(function (id) {
        
        // get the name of the current table
        var tn = AppGini.currentTableName()

        // call our function, pass tablename and the (=one) primary key
        myBatchAction1(tn, id);

    }, "flash", "Show alert for row");

});