siensis/kpacrud

KpaCrud Library permits to generate automatically CRUD pages from a DB table

dev-master 2024-03-11 19:12 UTC

MIT

• JmFxR

• database
• codeigniter
• crud

README

• KpaCrud Library
• Install
  • Install with composer
  • Install manually
• Publish command
• Constructor
• Routes file
• Config file parameters
• Method setConfig
• Method setTable
• Method setPrimaryKey
• Method setColumns
• Method setRelation
• Method addWhere
• Method limit
• Method setColumnsInfo
  • Available parameters
  • Set field name
  • Field types and samples
    • Number field type
    • Range field
    • Make a field required
    • Make a field Invisible
    • Checkbox field
    • Date field with default value in Add page
    • Datetime field with default value in Add page
    • Password field type
    • Dropdown field type
• Method hideHeadLink
• Method addPostAddCallBack and addPostEditCallBack
• Functions isViewMode, isExportMode, isAddMode, isEditMode, isDelMode, isTrashMode
• Method addItemFunction
• Method addItemLink
• Library Exceptions

KpaCrud Library

• Samples and how to's
• Change list
• TODO

Install

Install with composer

Option 1:

You need to add SIENSIS/KpaCrud require with composer tool.

> composer require siensis/kpacrud:dev-master

Option 2:

or modify composer.json and add the package to require items into composer.json

    "require": {
        "siensis/kpacrud": "dev-master"
    },

Finally

Execute composer update command to update your project settings

> composer update

💡 Idea

If you have any problem, probably you need to update you composer, executing:

composer self-update --2

Install manually

Download KpaCrud project and extract into your project in a ThirdPary folder, with this structure:

📁 app

📁 public

📁 tests

📁 vendor

📁 ThirdParty

|---- 📁 SIENSIS

|---- |---:file_folder: KpaCrud

Then you need modify autoload config file app/Config/Autoload.php and add your new PSR4 package path.

public $psr4 = [
    APP_NAMESPACE => APPPATH, // For custom app namespace
    'Config'      => APPPATH . 'Config',
    'SIENSIS\KpaCrud' => ROOTPATH . 'ThirdParty'.DIRECTORY_SEPARATOR.'SIENSIS'.DIRECTORY_SEPARATOR.'KpaCrud'.DIRECTORY_SEPARATOR.'src'
];

💡 Idea

Constant DIRECTORY_SEPARATOR is used to prevent path problems in Linux or Windows servers

Publish command

KpaCrud has their command kpacrud:publish to generate automatically a sample controller, a view sample, a custom config file and the KpaCrud lang files into your App folder.

To generate this files, you need to execute this command:

> php spark kpacrud:publish
Publish demo Controller? [y, n]:
Publish Views? [y, n]:
Publish Config file? [y, n]:
Publish Language file? [y, n]:

If files already exists, publish command ask you for confirmation. Otherwise if you sure to overwrite files, you can call kpacrud:publish with -f option, like:

> php spark kpacrud:publish -f

Constructor

You can save all config parameters into KpaCrud.php file in App\Config folder.

$crud = new KpaCrud(); //loads default configuration

Loads default parameters with configDefaultName as the config collection parameters. If you would like to load another collection, you can indicate it in constructor.

With this sample you KpaCrud library loads listView defined parameters.

$crud = new KpaCrud('listView'); //loads listView configuration

Routes file

KpaCrud library works with GET and POST methods, you need to create a GET and POST route to your controller function.

$routes->match(['get','post'],'/route/to/crud', 'SampleKpaCrudController::demo_function');

POST Method is used by KpaCrud in Add submit, Delete confirm and Edit submit.

Config file parameters

In the file App\Config\KpaCrud.php you can can store parameters collections identified with a name and the collection parameter used as default.

Param name	Type	Default	Description
editable	boolean	true	Defines if row has edit button
removable	boolean	true	Defines if row has delete button
Table tools
lang	string		Defines the URL of JS file language for Datatables JQuery tool
sortable	boolean	true	Defines if table has enabled the sortable feature
filterable	boolean	true	Defines if table has enabled the searching tool
paging	boolean	true	Defines if table has enabled the paging tools
numerate	boolean	true	Defines library numerate rows
Table features
pagingType	string		Determines the paging type, values are: numbers, simple, simple_numbers, full, full_numbers, first_last_numbers
defaultPageSize	int		Determines the page size set as default
rememberState	boolean	false	Defines if table remembers last order column, search, etc
Right toolbar
add_button	boolean	true	Enables add button in top right toolbar
show_button	boolean	true	Enables show button in list items
recycled_button	boolean	true	Enables trash buttons in top right toolbar (Empty trash, show trash)
exportXLS	boolean	true	Enables export XLS button in top right toolbar
print	boolean	true	Enables print button in top right toolbar
Left toolbar
multidelete	boolean	true	Enables the multi select feature in table list to remove item or to move to trash if softDelete is enabled
deletepermanent	boolean	true	Enables the multi select feature in table list to remove item permanently if softDelete is enabled
Model features
useSoftDeletes	boolean	true	Enables the soft delete feature, then items are mark as delete and they can use trash view
showTimestamps	boolean	false	Enables to show fields created_at and updated_at in view page
createdField	string	'created_at'	Name of created_at field into database
updatedField	string	'updated_at'	Name of update_at field into database
deletedField	string	'deleted_at'	Name of deleted_at field into database

In config file you can define the default collection with configDefaultName.

The KpaCrud config file provided, are defined onlyView, listView and default (acts as fullView ).

Method setConfig

You can set config parameters after object Library is created. The function setConfig can change all config parameters if you set a collection name as a parameter.

$crud->setConfig('onlyView');

even, you can change only a parameter, like:

$crud->setConfig(['editable'=>false]);                     // Sets editable configuration to false
$crud->setConfig(['editable'=>false,'removable'=>false]);  //Sets editable and removable config parameter to false 

See also How to create your custom App\KpaCrud config file

Method setTable

This method sets table name to generate CRUD pages, when you set table name, method can detect primary key. By default, setTable doesn't detect primary key. To load automatically primary key, you need to set true the loadPrimaryKeys function flag, like this sample:

$crud->setTable('news', true);    // Primary key autoload feature

otherwise, you can only specify table name.

$crud->setTable('news');

Method setPrimaryKey

This method adds primary key to CRUD Library, you can use it if you doesn't use automatic primary key load. You can call function for every key, if your table has more than a primary key.

$crud = new KpaCrud();

$crud->setTable('tokens');
$crud->setPrimaryKey('tokenid');
$crud->setPrimaryKey('subject');

⚠️ Exception

If the primary key string field doesn't exists, method will throw an exception

Method setColumns

This method will permit to set columns that will be shown in CRUD Page view or CRUD Trash view if enabled.

$crud = new KpaCrud('listView');        // loads listView configuration
$crud->setTable('news');                // load news table
$crud->setPrimaryKey('id');             // set primary key to id field
$crud->setColumns(['id', 'title', 'data_pub']); // set fields to show in listView

⚠️ Exception

Function throws this

• Table is null or not defined
• Table doesn't exists in database
• Field doesn't exists in table

Method setRelation

With this method you can set a relation 1=>N from a table to another one, for CRUD operations.

  $crud = new KpaCrud('listView');                          // loads listView configuration    
 
  $crud->setTable('auth_groups_users');                     // set table name
 
  $crud->setPrimaryKey('group_id');                         // set primary key
  $crud->setPrimaryKey('user_id');                          // set primary key
 
 // function setRelation($fieldName, $relatedTable, $relatedField, $display_as = null)

 // display_as is the column name to show in edit / view mode
 // if not set, relatedfield is shown
  $crud->setRelation('group_id', 'auth_groups', 'id', 'name');
  $crud->setRelation('user_id', 'users', 'id', 'username');

The display_as parameter is to indicated the field name from related table, to show instead relatedField. If parameter is null, will show first upper case related field name

They can display more than a relation, like example.

Method addWhere

This method permits to filter data show in the KpaCrud admin table. You can set filter as an associative array, or you can set SQL where expression as string.

The third parameter permits you to use OR conjuntion in a where clause

    $crud->addWhere ("id","3");
    $curd->addWhere ("id","4", true);

This clause generates

WHERE id=3 OR id=4

⚠️ WARNING!!

If you use parameters with this function, you need to check it to avoid SQL injection

Method limit

This method adds limit clause to database query, usefull to show limited data. Sintax as codeigniter querybuilder limit function

  $crud->limit(10);   // Produces: LIMIT 10

  $crud->limit(10, 20);  // Produces: LIMIT 20, 10

Method orderBy

This method Adds order by clause to database query, usefull to show ordered data. Sintax as codeigniter querybuilder limit function

  $crud->orderBy('title', 'DESC');  // Produces: ORDER BY `title` DESC

  $crud->orderBy('title DESC, name ASC');  // Produces: ORDER BY `title` DESC, `name` ASC

  $crud->orderBy('title', 'DESC');  $builder->orderBy('name', 'ASC');   // Produces: ORDER BY `title` DESC, `name` ASC

  $crud->orderBy('title', 'RANDOM');  // Produces: ORDER BY RAND()

  $crud->orderBy(42, 'RANDOM');  // Produces: ORDER BY RAND(42)

Method setColumnsInfo

Available parameters

The function setColumnsInfo permits to customize every database field.

Parameter	Type	Description
name	string	Field name to show user in pages
type	string	Availables field types are: DEFAULT_FIELD_TYPE, READONLY_FIELD_TYPE, INVISIBLE_FIELD_TYPE, EMAIL_FIELD_TYPE, CHECKBOX_FIELD_TYPE,NUMBER_FIELD_TYPE, RANGE_FIELD_TYPE, DATE_FIELD_TYPE, DATETIME_FIELD_TYPE, TEXTAREA_FIELD_TYPE (Check field types)
default	string	Field default value in add page
check_value	string,bool,integer	Value stored when a checkbox is checked. DEFAULT=1
uncheck_value	string,bool,integer	Value stored when a checkbox is unchecked. DEFAULT=0
html_atts	array[string]	Others html attributes to add to field, like: required, placeholder, pattern, title, min, max, step...
options	array	Options to show in a dropdown field
excludes	array	Values that are excluded to show into field

Set field name

You can set the field name with the properties associative array like this sample:

'dbfieldname' => [
    'name' => 'Field name to show',
],

or you can set it directly, but in this last version, you can only set the name for a db field.

'dbfieldname' => 'Field name to show',

Field types and samples

Number field type

'dbfieldname' => [
    'name' => 'Demo number field',
    'type' => KpaCrud::NUMBER_FIELD_TYPE,
    'default' => '25',
    'html_atts' => [
        'min="1"',
        'max="50"',
    ]
],

Range field

'dbfieldname' => [
    'name' => 'Demo text field',
    'type' => KpaCrud::RANGE_FIELD_TYPE,
    'default' => '25',
    'html_atts' => [        // html_atts are optional, but useful to costumize page
        'min="1"',
        'max="50"',
        'step="5"',
    ]
],

Make a field required

'dbfieldname' => [
    'name' => 'Demo text field',
    'html_atts' => [
        "required", 
        "placeholder=\"Add your info here\""
    ],
],

Make a field Invisible

This field will be invisible in all views

'dbfieldname' => [
    'type' => KpaCrud::INVISIBLE_FIELD_TYPE
],

Make a field READ ONLY

This field will be read only in add or edit view

'dbfieldname' => [
    'type' => KpaCrud::READONLY_FIELD_TYPE
],

Checkbox field

'dbfieldname' => [
    'name' => 'Demo text field',
    'type' => KpaCrud::CHECKBOX_FIELD_TYPE, 
    'check_value' => '1',   // By default check_value=1. You can omit it is equal
    'uncheck_value' => '0'  // By default uncheck_value=0    
],

Date field with default value in Add page

'dbfieldtype' => [
    'type' => KpaCrud::DATE_FIELD_TYPE,
    'default' => '1-2-2022'  // you can set default date for add page
],

Datetime field with default value in Add page

'dbfieldtype' => [
    'type' => KpaCrud::DATETIME_FIELD_TYPE,
    'default' => '1-2-2022 15:43'  // you can set default date for add page
],

Password field type

This type permits to hide content data in edit page or new page. All fields typed as password are always hidden in view or delete views.

Password field type in the edit page adds a hidden form field to check programatically if user has changed the value. This feature permits you to combine with edit and new callback to store passwords hashed in you DB.

See Samples file

Dropdown field type

You can create a custom dropdown item, to control values introduced in a field by user. You can define dropdown values with an associative array.

To make an identic checkbox with a dropdown, you can set item-value only, like this.

'active' => [ 'type' => KpaCrud::DROPDOWN_FIELD_TYPE, 'options' => ["Disabled", "Active"], 'html_atts'=>[ "required", ] ],

'active' => [ 'type' => KpaCrud::DROPDOWN_FIELD_TYPE, 'options' => ["0"=>"Disabled", "1"=>"Active"], 'html_atts'=>[ "required", ] ],

This samples generates

<select name="data_active" id="data_active" required="">
    <option value="0">Disabled</option>
    <option value="1">Active</option>
</select>

If you need to show a select value item in a dropdown, you can do it easily adding a null index item. Like this sample.

'active' => [
    'type' => KpaCrud::DROPDOWN_FIELD_TYPE,
    'options' => [""=>"Select option","Disabled","Active"],
    'html_atts'=>[
        "required",
    ]
],

This samples generates

<select name="data_active" id="data_active" required="">
    <option value="" selected="selected">Select option</option>
    <option value="0">Disabled</option>
    <option value="1">Active</option>
</select>

Method hideHeadLink

If you need to hide CSS/JS from head, you can use hideHeadLink function. Every link has its own id, the availables ones are:

ID	Description
js-query	JQuery Javascript CDN
js-bootstrap	Bootstrap JS file
js-datatables	Datatables plugin JS file
js-datatables-boot	Datatables JS file for bootstrap theme
css-bootstrap	Bootstrap CSS file
css-datatables-boot	Datatables CSS for bootstrap theme
css-fontawesome	Fontawesome CSS file

See "How to change bootstrap, jquery or CSS/JS head links" for a sample.

Method addPostAddCallBack and addPostEditCallBack

If you need to get post data to change anythig before KpaCrud uses this info to store it in database, you need to set an add or edit callback.

The function will receive post data and they must return post data modified or null if you need to cancel event, in this case KpaCrud showns a cancel message like: Error callback function cancel operation

Post data fields will use the name according this structure:

data_ + DATABASE_FIELD_NAME

See "How to set a callback to store hashed password" for a sample.

Functions isViewMode, isExportMode, isAddMode, isEditMode, isDelMode, isTrashMode

The functions functions isViewMode, isExportMode, isAddMode, isEditMode, isDelMode, isTrashMode permits you to know KpaCrud mode, to customize KpaCrud aspect.

Sample: You need to export all database fields but in list mode you would like to show only id and description fields.

See "How to custom parameters according KpaCrud view mode" for a sample.

Method addItemFunction

This function permits to declare a new icon function in every register. The function used as callback may be defined in your controllers.

The callback function used may returns a view as string. KpaCrud library uses this html information to show them in KpaCrud interface.

If you need a function to be called afterly, as post page or other like this, you can define invisible functions.

See How to add a function for every register for a sample.

Method addItemLink

This function permits to declare a new icon link for every register. The function used as callback may be defined in your controllers.

        $crud->addItemLink('view', 'fa-file-o', base_url('route/to/link'), 'Tooltip for icon button');
        // GENERATES <a href="ROUTE/[IDs_SEPARETED_BY_SLASH]" title="HELP TEXT">ICON</a>

        $crud->addItemLink('show', 'fa-file-o', [base_url('route/to/link'),'hash'], 'Tooltip for icon button'));
        // GENERATES <a href="ROUTE/[IDs_SEPARETED_BY_SLASH_HASHED]" title="HELP TEXT">ICON</a>

Library Exceptions

Exception ID	Exception
1, 4, 8	Table name is null
2, 5, 9	Table not exists in DB
3, 6	Field name not exists	You try to set a field name as ID or show as a column in list view, and this field doesn't exists
7	Field type unknown	Check available field types in documentation
10	ID Field name set to null