v3.x
v3.x (Latest)
v2.x
v1.x

Migrating from v2 to v3

Table of contents:


In short the upgrade from version 2 to version 3 should be very straight forward. Since we haven't changed a lot the API of the library, you should be able to upgrade without any problems. There are 3 main areas that you should be aware of:

The biggest change that you will actually notice is the package new name for Composer.

The package previously known as: 

grocerycrud/enterprise

has been renamed to:

grocery-crud/enterprise

with the inclusion of a dash in the name.

The documentation now recommends using Composer as the primary method for installation.

In the past we were mainly suggesting to copy the library and the assets folders manually. Currently, we advise users to use Composer as the preferred method instead. This is because composer is a popular dependency manager for PHP and is widely used in the PHP community anyway!

It makes it easy to manage the package and its dependencies, ensuring that everything is properly installed and configured for use. Using composer also makes it easier to update the package when new versions are released, as it handles all the necessary dependencies and file management automatically.

The assets folder for our installation packages has been moved from public/grocery-crud to public/vendor/grocery-crud. This change was inspired by the assets folder structure used by Laravel Public Assets and was made to provide a more familiar structure for the public assets folder.

Breaking changes:

Configuration arguments that has been removed:

New configuration arguments:

Configuration changes:

Functions that has been removed:

API changes:

We have changed the way that we upload. Now the upload is triggered after the submit form and the UI is the standard native upload input.

Since we are using the new ReactJS library we have changed the way that we load the library. So instead of loading the library with the below code:

// code before
$(document).ready(function () {
    $('.gc-container').groceryCrud();
});

We now load the library with the below code instead:

// code now
groceryCrudLoader(document.querySelectorAll(".grocery-crud")[0]);

Also, the settings object is now called by the second parameter of the groceryCrudLoader function instead of the first one that we've used before.

For example, previously we had:

// code before
$('.gc-container').groceryCrud({
    callbackBeforeInsert: function () {
        console.log('callback that is called right before the insert');
    }
});

And now we should have:

// code now
groceryCrudLoader(document.querySelectorAll(".grocery-crud")[0], {
    callbackBeforeInsert: function () {
        console.log('callback that is called right before the insert');
    }
});

Keep in mind that for security reasons, the publishing of the events by default are now configured to be false. This means that in order to start using the JavaScript events you need to set the configuration publish_events to true first.

All the events has changed and there will come from the redux action by replacing / with . starting with gcrud. For example the redux action type datagrid/data-render will be published as an event gcrud.datagrid.data-render instead.

Also, as now the published events are actual JavaScript events, all the payload will be available through the property name detail according to the latest Custom Event docs.

All the event names are available through the documentation page of JavaScript events

Keep in mind that since we now have the publish_events configuration, we are now suggesting to use the JavaScript events instead of the callbacks. They are easier to implement, and you don't need any extra steps to start using them. For more information about the JavaScript events check the documentation page of JavaScript events

Settings Removals:

New settings:

actionButtonsMultiple: [{
     iconName: 'smile',
     label: 'Smiley',
     onClick: function ({selectedIds}) {
         console.log(selectedIds);
     }
}],

Settings changes:

The settings object (second parameter of the loader) has slight changes on the callbacks as well. The callbacks are now getting an object instead of the arguments that we had before.

For example previously we had the below code:

// code before
callbackBeforeUpdate: function (data, primaryKeyValue) {
    console.log('callback that is called right before the update', 
       {data, primaryKeyValue}
    );
},

And now we should have:

// code now
callbackBeforeUpdate: ({data, primaryKeyValue}) => { // <-- We now have an object parameter
    console.log('callback that is called right before the update', 
       {data, primaryKeyValue}
    );
},