- KpaCrud Library
- Install
- Publish command
- Constructor
- Routes file
- Config file parameters
- Method setConfig
- Method setTable
- Method setPrimaryKey
- Method setColumns
- Method setRelation
- Method addWhere
- Method limit
- Method setColumnsInfo
- Method hideHeadLink
- Method addPostAddCallBack and addPostEditCallBack
- Functions isViewMode, isExportMode, isAddMode, isEditMode, isDelMode, isTrashMode
- Method addItemFunction
- Method addItemLink
- Library Exceptions
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
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
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
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
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
.
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 |
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 ).
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
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');
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');
If the primary key string field doesn't exists, method will throw an exception
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
Function throws this
- Table is null or not defined
- Table doesn't exists in database
- Field doesn't exists in table
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.
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
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
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)
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 |
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',
'dbfieldname' => [
'name' => 'Demo number field',
'type' => KpaCrud::NUMBER_FIELD_TYPE,
'default' => '25',
'html_atts' => [
'min="1"',
'max="50"',
]
],
'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"',
]
],
'dbfieldname' => [
'name' => 'Demo text field',
'html_atts' => [
"required",
"placeholder=\"Add your info here\""
],
],
This field will be invisible in all views
'dbfieldname' => [
'type' => KpaCrud::INVISIBLE_FIELD_TYPE
],
This field will be read only in add or edit view
'dbfieldname' => [
'type' => KpaCrud::READONLY_FIELD_TYPE
],
'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
],
'dbfieldtype' => [
'type' => KpaCrud::DATE_FIELD_TYPE,
'default' => '1-2-2022' // you can set default date for add page
],
'dbfieldtype' => [
'type' => KpaCrud::DATETIME_FIELD_TYPE,
'default' => '1-2-2022 15:43' // you can set default date for add page
],
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
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>
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.
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.
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.
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.
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>
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 |