From 4e75af67edc2014f09f692a8e10e997ac0ca6def Mon Sep 17 00:00:00 2001 From: Thomas Kuschel Date: Wed, 4 Oct 2023 18:06:13 +0200 Subject: [PATCH] ADD database tables b_2 --- README.md | 171 +++++++++++++++++++++++++++++ admin/sql/install.mysql.utf8.sql | 8 +- admin/sql/uninstall.mysql.utf8.sql | 2 +- admin/src/Table/DepotTable | 24 ++++ depot.xml | 48 +++++--- 5 files changed, 235 insertions(+), 18 deletions(-) create mode 100644 admin/src/Table/DepotTable diff --git a/README.md b/README.md index 1a261cc..339293f 100644 --- a/README.md +++ b/README.md @@ -112,3 +112,174 @@ the directory /admin/language/en-GB/ naming it - com_depot.sys.ini --- + +### Creating and managing Joomla database (b2_database) + +With the new git branch **b2_database** we continue our workflow. + +Joomla usually manage its content with a database. In our component, we use +a MariaDB database. At the time of development of this component we have PHP8.2, +and we use Mariadb database with version from 11.1, +client 15.2 for Linux (x86_64) using readline 5.1 +We support MySQL and MariaDB; not tested support for PostgreSQL. + +In the manifest file \.xml, here the file **depot.xml**, +there are installation instructions to "install", "uninstall", and +"update" the Joomla extension/component. + +The SQL plain text files are stored in and as: + +- admin/sql/ + - install.mysql.utf8.sql + - uninstall.mysql.utf8.sql + +- admin/sql/updates/mysql/ + - 0.0.1.sql + - 0.0.4.sql + - 0.0.5.sql + +#### Database table installation +1. When the component is installed for the first time, the file +**install.mysql.utf8.sql** is executed. +1. If the component is already installed, the update +scenario comes into play, the folder **admin/sql/updates/mysql/**: Only the files with higher version +numbers than the installed version of the component will be +executed in ascending order.
+Hint: The version of the installed component is stored in the +Joomla's table "#__schemas". + +The "#__"-prefix is substituted automatically with the database prefix, (e.g. "jm_") which is defined in the configuration file (configuration.php) of the installed Joomla version as parameter $dbprefix. + +**install.mysql.utf8.sql** +```sql +DROP TABLE IF EXISTS `#__depot`; +CREATE TABLE `#__depot`( + `id` SERIAL, + `component_name` VARCHAR(1024) CHARACTER SET ascii COLLATE ascii_general_ci NULL DEFAULT NULL + COMMENT 'unique component name (ASCII characters only)', + `alias` VARCHAR(1024) NOT NULL DEFAULT '', + `description` VARCHAR(4000) NOT NULL DEFAULT '', + `quantity` INT(10) UNSIGNED NOT NULL DEFAULT 0, + `quantity_exp` INT(11) NOT NULL DEFAULT 0 + COMMENT 'Exponent of the quantity (10^x of the number, usually 0 i.e. 10⁰)', + `asset_id` INT(10) UNSIGNED NOT NULL DEFAULT 0 COMMENT 'FK to the #__assets table.', + `created` DATETIME NOT NULL DEFAULT '0000-00-00 00:00:00', + `created_by` INT(10) UNSIGNED NOT NULL DEFAULT 0, + `checked_out` INT(11) NOT NULL DEFAULT 0, + `checked_out_time` DATETIME NOT NULL DEFAULT '0000-00-00 00:00:00', + `modified` DATETIME NOT NULL DEFAULT '0000-00-00 00:00:00', + `modified_by` INT(10) UNSIGNED NOT NULL DEFAULT 0, + `path` VARCHAR(400) NOT NULL DEFAULT '', + `state` TINYINT(4) NOT NULL DEFAULT 0 + COMMENT 'Published=1,Unpublished=0,Archived=2,Trashed=-2', + `access` TINYINT(4) NOT NULL DEFAULT 0, + `params` VARCHAR(1024) NOT NULL DEFAULT '', + `image` VARCHAR(1024) NOT NULL DEFAULT '', + `ordering` INT(11) NOT NULL DEFAULT 0, + `version` int unsigned NOT NULL DEFAULT 1, + -- references to other tables: + `category_id` INT(11) NOT NULL DEFAULT 0, + `datasheet_id` INT(11) NOT NULL DEFAULT 0, + `datasheet_alt` VARCHAR(1024) NOT NULL DEFAULT '', + `manufacturer_id` INT(11) NOT NULL DEFAULT 0, + `stock_id` INT(11) NOT NULL DEFAULT 0, + PRIMARY KEY (`id`), + KEY `idx_state` (`state`), + KEY `idx_stock_id` (`stock_id`), + KEY `idx_manufacturer` (`manufacturer_id`), + UNIQUE KEY `aliasindex` (`alias`,`manufacturer_id`,`stock_id`) +) ENGINE=InnoDB + AUTO_INCREMENT=0 + DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci; + +INSERT INTO `#__depot` (`component_name`,`alias`,`description`,`quantity`,`created`, + `ordering`,`state`,`manufacturer_id`) VALUES + ('1N5404','1n5404','diode, rectifier 3A',9,'2023-09-25 15:00:00',1,1,1), + ('1N4148','1n4148','diode, general purpose',1234,'2023-09-25 15:15:15',2,1,2); +``` +The table is created in the database when the component is installed. +Also two lines of sample data are inserted into the table "#__depot". + +#### Database table uninstallation +When the component is uninstalled the +**uninstall.mysql.utf8 sql** is executed. +We drop the used tables from the database. + +**install.mysql.utf8.sql** +```sql +DROP TABLE IF EXISTS `#__depot`; +``` +#### Database table update +When the component is updated the +**admin/sql/updates/mysql** folder with its files is executed. + +Even if you do not need a database update, you can add an empty file in admin/sql/updates/mysql/0.0.2.sql to initialize the schema version. + +In future versions, if you plan to use database tables, the update can be performed automatically. +We create an empty file, just with a comment "-- version 0.0.2" +**admin/sql/updates/mysql/0.0.2.sql** + +```sql +-- version 0.0.2 +``` + +#### Manifest file for extensions +The sql files are only executed if they exist in the \.xml manifest file. We add this after the namespace tag, just before the files information tag: +```php + + + sql/install.mysql.utf8.sql + + + + + sql/uninstall.mysql.utf8.sql + + + + + sql/updates/mysql + + +``` +The **\ tag** of the manifest must be updated to 0.0.2 and +also add the sql folder in the administration files section. + +#### Table class +**src/table/DepotTable.php** + +For each database table, you have to define a table class. The model +asks the table to get information or perform database operations. + +This table class has to be defined in admin/src/Table/DepotTable.php file. + +```php + -- @copyright (C) 2023 KW4NZ, -- @license GNU General Public License version 2 or later; see LICENSE.md --- @since 0.0.1 +-- @since 0.0.2 DROP TABLE IF EXISTS `#__depot`; CREATE TABLE `#__depot`( @@ -13,7 +13,8 @@ CREATE TABLE `#__depot`( `alias` VARCHAR(1024) NOT NULL DEFAULT '', `description` VARCHAR(4000) NOT NULL DEFAULT '', `quantity` INT(10) UNSIGNED NOT NULL DEFAULT 0, - `quantity_exp` INT(11) NOT NULL DEFAULT 0 COMMENT 'Exponent of the quantity (10^x of the number, usually 0 i.e. 10⁰)', + `quantity_exp` INT(11) NOT NULL DEFAULT 0 + COMMENT 'Exponent of the quantity (10^x of the number, usually 0 i.e. 10⁰)', `asset_id` INT(10) UNSIGNED NOT NULL DEFAULT 0 COMMENT 'FK to the #__assets table.', `created` DATETIME NOT NULL DEFAULT '0000-00-00 00:00:00', `created_by` INT(10) UNSIGNED NOT NULL DEFAULT 0, @@ -22,7 +23,8 @@ CREATE TABLE `#__depot`( `modified` DATETIME NOT NULL DEFAULT '0000-00-00 00:00:00', `modified_by` INT(10) UNSIGNED NOT NULL DEFAULT 0, `path` VARCHAR(400) NOT NULL DEFAULT '', - `state` TINYINT(4) NOT NULL DEFAULT 0 COMMENT 'Published=1,Unpublished=0,Archived=2,Trashed=-2', + `state` TINYINT(4) NOT NULL DEFAULT 0 + COMMENT 'Published=1,Unpublished=0,Archived=2,Trashed=-2', `access` TINYINT(4) NOT NULL DEFAULT 0, `params` VARCHAR(1024) NOT NULL DEFAULT '', `image` VARCHAR(1024) NOT NULL DEFAULT '', diff --git a/admin/sql/uninstall.mysql.utf8.sql b/admin/sql/uninstall.mysql.utf8.sql index 5fc1695..33a9162 100644 --- a/admin/sql/uninstall.mysql.utf8.sql +++ b/admin/sql/uninstall.mysql.utf8.sql @@ -3,6 +3,6 @@ -- @author Thomas Kuschel -- @copyright (C) 2023 KW4NZ, -- @license GNU General Public License version 2 or later; see LICENSE.md --- @since 0.0.1 +-- @since 0.0.2 DROP TABLE IF EXISTS `#__depot`; diff --git a/admin/src/Table/DepotTable b/admin/src/Table/DepotTable new file mode 100644 index 0000000..aaf2a12 --- /dev/null +++ b/admin/src/Table/DepotTable @@ -0,0 +1,24 @@ + + * @copyright (C) 2023 KW4NZ, + * @license GNU General Public License version 2 or later; see LICENSE.md + * @since 0.0.2 + */ + +namespace KW4NZ\Component\Depot\Administrator\Table; + +use Joomla\CMS\Table\Table; +use Joomla\Database\DatabaseDriver; + +\defined('_JEXEC') or die; + +class DepotTable extends Table +{ + function __contruct(DatabaseDriver $db) + { + parent::__contruct('#__depot', 'id', $db); + } +} diff --git a/depot.xml b/depot.xml index d733e84..a1ac215 100644 --- a/depot.xml +++ b/depot.xml @@ -2,14 +2,29 @@ Depot KW4NZ - 2023-10-02 + 2023-10-04 (C) KW4NZ Thomas Kuschel GPL v2 +; see LICENSE.md thomas@kuschel.at https://kuschel.at - 0.0.1 + 0.0.2 COM_DEPOT_XML_DESCRIPTION KW4NZ\Component\Depot + + + sql/install.mysql.utf8.sql + + + + + sql/uninstall.mysql.utf8.sql + + + + + sql/updates/mysql + + CODING_STANDARDS.md LICENSE.md @@ -20,9 +35,24 @@ Note that all & must be escaped to & for the file to be valid XML and be parsed by the installer --> - COM_DEPOT_MENU + COM_DEPOT_MENU - COM_DEPOT_MENU + + COM_DEPOT_MENU + + + COM_DEPOT_STOCK_MENU + services @@ -35,14 +65,4 @@ en-GB/com_depot.sys.ini - - - sql/install.mysql.utf8.sql - - - - - sql/uninstall.mysql.utf8.sql - -