Skip to content

Commit a0a3801

Browse files
author
Pascal MARTINEZ
committed
First official version of the module
0 parents  commit a0a3801

15 files changed

+1419
-0
lines changed

‎CHANGELOG.md

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# CHANGE LOG: Theme chooser (z4m_themechooser)
2+
3+
## Version 1.0, 2024-10-25
4+
First version.

‎LICENSE.TXT

+674
Large diffs are not rendered by default.

‎README.md

+72
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# ZnetDK 4 Module theme chooser
2+
Allows the ZnetDK 4 Mobile application to be displayed with a dark theme.
3+
4+
![Screenshot of the Theme chooser UI provided by the ZnetDK 4 Mobile 'z4m_themechooser' module](https://mobile.znetdk.fr/applications/default/public/images/modules/z4m_themechooser/screenshot.png?v1)
5+
6+
## FEATURES
7+
This module add a "Theme" button to the User Panel.
8+
When clicked, a modal dialog is displayed to apply the dark theme or to come
9+
back to the light theme.
10+
The favorite theme is saved in database for the logged in user.
11+
12+
## REQUIREMENTS
13+
- [ZnetDK 4 Mobile](/../../../znetdk4mobile) version 3.2 or higher,
14+
- A **MySQL** database is configured to store the application data,
15+
- **PHP version 7.4** or higher,
16+
- Authentication is enabled
17+
([`CFG_AUTHENT_REQUIRED`](https://mobile.znetdk.fr/settings#z4m-settings-auth-required)
18+
is `TRUE` in the App's
19+
[`config.php`](/../../../znetdk4mobile/blob/master/applications/default/app/config.php)).
20+
21+
## INSTALLATION
22+
1. Copy module's code in the `./engine/modules/z4m_themechooser/` subdirectory,
23+
2. Edit the App's [`config.php`](/../../../znetdk4mobile/blob/master/applications/default/app/config.php)
24+
located in the [`./applications/default/app/`](/../../../znetdk4mobile/tree/master/applications/default/app/) subfolder and set the path or URL of your dark theme CSS stylesheet to the `MOD_Z4M_THEMECHOOSER_CSS_DARK_THEME` PHP constant.
25+
If the app logo to be displayed for dark theme is different from the one for light theme, also set the path of your light and dark logos to the `MOD_Z4M_THEMECHOOSER_LOGO_LIGHT_THEME` and `MOD_Z4M_THEMECHOOSER_LOGO_DARK_THEME` PHP constants.
26+
For example:
27+
```php
28+
define('MOD_Z4M_THEMECHOOSER_CSS_DARK_THEME', 'applications/'.ZNETDK_APP_NAME.'/public/css/theme-dark.css');
29+
// Optional: the paths of the light and dark logos
30+
define('MOD_Z4M_THEMECHOOSER_LOGO_LIGHT_THEME', 'applications/'.ZNETDK_APP_NAME.'/public/images/logo-light.png');
31+
define('MOD_Z4M_THEMECHOOSER_LOGO_DARK_THEME', 'applications/'.ZNETDK_APP_NAME.'/public/images/logo-dark.png');
32+
```
33+
3. In option, If the app logo to be displayed for dark theme is different from the one for light theme,
34+
edit the [`locale.php`](/../../../znetdk4mobile/blob/master/applications/default/app/lang/locale.php) script of your application
35+
and set the `LC_HEAD_IMG_LOGO` PHP constant to the path of the dark logo if dark theme is to be displayed.
36+
For example:
37+
```php
38+
/* Heading images */
39+
use z4m_themechooser\mod\controller\Users;
40+
if (Users::getUserTheme() === MOD_Z4M_THEMECHOOSER_CSS_DARK_THEME) {
41+
define('LC_HEAD_IMG_LOGO', MOD_Z4M_THEMECHOOSER_LOGO_DARK_THEME);
42+
} else {
43+
define('LC_HEAD_IMG_LOGO', MOD_Z4M_THEMECHOOSER_LOGO_LIGHT_THEME);
44+
}
45+
```
46+
47+
## TRANSLATIONS
48+
This module is translated in **French**, **English** and **Spanish** languages.
49+
To translate this module in another language or change the standard
50+
translations:
51+
1. Copy in the clipboard the PHP constants declared within the
52+
[`locale_en.php`](mod/lang/locale_en.php) script of the module,
53+
2. Paste them from the clipboard within the
54+
[`locale.php`](/../../../znetdk4mobile/blob/master/applications/default/app/lang/locale.php) script of your application,
55+
3. Finally, translate each text associated with these PHP constants into your own language.
56+
57+
## ISSUES
58+
The `zdk_user_themes` SQL table is created automatically by the module
59+
when the user's favorite theme is read or saved for the first time.
60+
If the MySQL user declared through the
61+
[`CFG_SQL_APPL_USR`](https://mobile.znetdk.fr/settings#z4m-settings-db-user)
62+
PHP constant does not have `CREATE` privilege, the module can't create the
63+
required SQL table.
64+
In this case, you can create the `zdk_user_themes` SQL table by importing
65+
in MySQL or phpMyAdmin the script
66+
[`z4m_themechooser.sql`](mod/sql/z4m_themechooser.sql) provided by the module.
67+
68+
## CHANGE LOG
69+
See [CHANGELOG.md](CHANGELOG.md) file.
70+
71+
## CONTRIBUTING
72+
Your contribution to the **ZnetDK 4 Mobile** project is welcome. Please refer to the [CONTRIBUTING.md](https://github.com/pascal-martinez/znetdk4mobile/blob/master/CONTRIBUTING.md) file.

‎mod/config.php

+63
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
<?php
2+
/**
3+
* ZnetDK, Starter Web Application for rapid & easy development
4+
* See official website https://mobile.znetdk.fr
5+
* Copyright (C) 2024 Pascal MARTINEZ ([email protected])
6+
* License GNU GPL https://www.gnu.org/licenses/gpl-3.0.html GNU GPL
7+
* --------------------------------------------------------------------
8+
* This program is free software: you can redistribute it and/or modify
9+
* it under the terms of the GNU General Public License as published by
10+
* the Free Software Foundation, either version 3 of the License, or
11+
* (at your option) any later version.
12+
* This program is distributed in the hope that it will be useful,
13+
* but WITHOUT ANY WARRANTY; without even the implied warranty of
14+
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15+
* GNU General Public License for more details.
16+
* You should have received a copy of the GNU General Public License
17+
* along with this program. If not, see <https://www.gnu.org/licenses/>.
18+
* --------------------------------------------------------------------
19+
* Parameters of the Theme chooser module
20+
*
21+
* File version: 1.0
22+
* Last update: 10/25/2024
23+
*/
24+
25+
/**
26+
* URL of the Dark theme stylesheet
27+
* @return string URL (NULL by default)
28+
*/
29+
define('MOD_Z4M_THEMECHOOSER_CSS_DARK_THEME', NULL);
30+
31+
/**
32+
* URL of the App's Dark logo
33+
* @return string URL (NULL by default)
34+
*/
35+
define('MOD_Z4M_THEMECHOOSER_LOGO_DARK_THEME', NULL);
36+
37+
/**
38+
* URL of the App's Light logo
39+
* @return string URL (NULL by default)
40+
*/
41+
define('MOD_Z4M_THEMECHOOSER_LOGO_LIGHT_THEME', NULL);
42+
43+
/**
44+
* Color scheme of the Theme chooser UI.
45+
* @var array|NULL Colors used to display the Theme chooser UI. The expected
46+
* array keys are 'modal_header', 'modal_content' ,'modal_footer',
47+
* 'modal_footer_border_top', 'btn_action', 'btn_hover' and 'btn_cancel'.
48+
* If NULL, default color CSS classes are applied.
49+
*/
50+
define('MOD_Z4M_THEMECHOOSER_COLOR_SCHEME', NULL);
51+
52+
/**
53+
* Path of the SQL script to update the database schema
54+
* @string Path of the SQL script
55+
*/
56+
define('MOD_Z4M_THEMECHOOSER_SQL_SCRIPT_PATH', ZNETDK_MOD_ROOT
57+
. DIRECTORY_SEPARATOR . 'z4m_themechooser' . DIRECTORY_SEPARATOR
58+
. 'mod' . DIRECTORY_SEPARATOR . 'sql' . DIRECTORY_SEPARATOR
59+
. 'z4m_themechooser.sql');
60+
61+
// VERSIONS
62+
define('MOD_Z4M_THEMECHOOSER_VERSION_NUMBER','1.0');
63+
define('MOD_Z4M_THEMECHOOSER_VERSION_DATE','2024-10-25');

‎mod/controller/Users.php

+56
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
<?php
2+
/**
3+
* ZnetDK, Starter Web Application for rapid & easy development
4+
* See official website https://mobile.znetdk.fr
5+
* Copyright (C) 2024 Pascal MARTINEZ ([email protected])
6+
* License GNU GPL https://www.gnu.org/licenses/gpl-3.0.html GNU GPL
7+
* --------------------------------------------------------------------
8+
* This program is free software: you can redistribute it and/or modify
9+
* it under the terms of the GNU General Public License as published by
10+
* the Free Software Foundation, either version 3 of the License, or
11+
* (at your option) any later version.
12+
* This program is distributed in the hope that it will be useful,
13+
* but WITHOUT ANY WARRANTY; without even the implied warranty of
14+
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15+
* GNU General Public License for more details.
16+
* You should have received a copy of the GNU General Public License
17+
* along with this program. If not, see <https://www.gnu.org/licenses/>.
18+
* --------------------------------------------------------------------
19+
* Theme chooser module application controller
20+
*
21+
* File version: 1.0
22+
* Last update: 10/25/2024
23+
*/
24+
namespace z4m_themechooser\mod\controller;
25+
26+
class Users extends \AppController {
27+
28+
static public function getUserTheme() {
29+
$theme = CFG_MOBILE_W3CSS_THEME;
30+
$userId = \UserSession::getUserId();
31+
try {
32+
$dao = new \SimpleDAO('zdk_user_themes');
33+
if (!$dao->doesTableExist() && !Z4mThemeChooserCtrl::createModuleSqlTable()) {
34+
throw new \Exception('SQL Table is missing and its creation failed.');
35+
}
36+
$rows = $dao->getRowsForCondition('user_id = ?', $userId);
37+
if (count($rows) > 0 && $rows[0]['theme_name'] === 'dark') {
38+
$theme = MOD_Z4M_THEMECHOOSER_CSS_DARK_THEME;
39+
}
40+
} catch (\Exception $ex) {
41+
\General::writeErrorLog(__METHOD__, $ex->getMessage());
42+
}
43+
return $theme;
44+
}
45+
46+
static public function onRemove($userId) {
47+
$dao = new \SimpleDAO('zdk_user_themes');
48+
if (!$dao->doesTableExist()) {
49+
return;
50+
}
51+
$rows = $dao->getRowsForCondition('user_id = ?', $userId);
52+
if (count($rows) > 0) {
53+
$dao->remove(NULL, FALSE);
54+
}
55+
}
56+
}

‎mod/controller/Z4mThemeChooserCtrl.php

+78
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
<?php
2+
/**
3+
* ZnetDK, Starter Web Application for rapid & easy development
4+
* See official website https://mobile.znetdk.fr
5+
* Copyright (C) 2024 Pascal MARTINEZ ([email protected])
6+
* License GNU GPL https://www.gnu.org/licenses/gpl-3.0.html GNU GPL
7+
* --------------------------------------------------------------------
8+
* This program is free software: you can redistribute it and/or modify
9+
* it under the terms of the GNU General Public License as published by
10+
* the Free Software Foundation, either version 3 of the License, or
11+
* (at your option) any later version.
12+
* This program is distributed in the hope that it will be useful,
13+
* but WITHOUT ANY WARRANTY; without even the implied warranty of
14+
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15+
* GNU General Public License for more details.
16+
* You should have received a copy of the GNU General Public License
17+
* along with this program. If not, see <https://www.gnu.org/licenses/>.
18+
* --------------------------------------------------------------------
19+
* Theme chooser module application controller
20+
*
21+
* File version: 1.0
22+
* Last update: 02/17/2024
23+
*/
24+
25+
namespace z4m_themechooser\mod\controller;
26+
27+
/**
28+
* Description of Z4mThemeChooserCtrl
29+
*/
30+
class Z4mThemeChooserCtrl extends \AppController {
31+
32+
static protected function action_store() {
33+
$request = new \Request();
34+
$response = new \Response();
35+
$userId = \UserSession::getUserId();
36+
if (is_null($userId) || $request->new_theme === NULL
37+
|| ($request->new_theme !== 'light' && $request->new_theme !== 'dark')) {
38+
$response->setFailedMessage(NULL, MOD_Z4M_THEMECHOOSER_ACTION_STORE_ERROR);
39+
return $response;
40+
}
41+
$row = ['user_id' => $userId, 'theme_name' => $request->new_theme];
42+
try {
43+
$dao = new \SimpleDAO('zdk_user_themes');
44+
if (!$dao->doesTableExist() && !self::createModuleSqlTable()) {
45+
throw new \Exception('SQL Table is missing and its creation failed.');
46+
}
47+
$rows = $dao->getRowsForCondition('user_id = ?', $userId);
48+
if (count($rows) > 0 && key_exists('id', $rows[0])) {
49+
$row['id'] = $rows[0]['id'];
50+
}
51+
$dao->store($row);
52+
$response->setSuccessMessage(NULL, MOD_Z4M_THEMECHOOSER_ACTION_STORE_OK);
53+
} catch (\Exception $ex) {
54+
\General::writeErrorLog(__METHOD__, $ex->getMessage());
55+
$response->setFailedMessage(NULL, MOD_Z4M_THEMECHOOSER_ACTION_STORE_ERROR);
56+
}
57+
return $response;
58+
}
59+
60+
static public function createModuleSqlTable() {
61+
if (!file_exists(MOD_Z4M_THEMECHOOSER_SQL_SCRIPT_PATH)) {
62+
\General::writeErrorLog(__METHOD__, "SQL script '"
63+
. MOD_Z4M_THEMECHOOSER_SQL_SCRIPT_PATH
64+
."' is missing.");
65+
return FALSE;
66+
}
67+
$sqlScript = file_get_contents(MOD_Z4M_THEMECHOOSER_SQL_SCRIPT_PATH);
68+
try {
69+
$db = \Database::getApplDbConnection();
70+
$db->exec($sqlScript);
71+
return TRUE;
72+
} catch (\Exception $ex) {
73+
\General::writeErrorLog(__METHOD__, $ex->getMessage());
74+
}
75+
return FALSE;
76+
}
77+
78+
}

‎mod/lang/locale_en.php

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
<?php
2+
/**
3+
* ZnetDK, Starter Web Application for rapid & easy development
4+
* See official website https://mobile.znetdk.fr
5+
* Copyright (C) 2024 Pascal MARTINEZ ([email protected])
6+
* License GNU GPL https://www.gnu.org/licenses/gpl-3.0.html GNU GPL
7+
* --------------------------------------------------------------------
8+
* This program is free software: you can redistribute it and/or modify
9+
* it under the terms of the GNU General Public License as published by
10+
* the Free Software Foundation, either version 3 of the License, or
11+
* (at your option) any later version.
12+
* This program is distributed in the hope that it will be useful,
13+
* but WITHOUT ANY WARRANTY; without even the implied warranty of
14+
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15+
* GNU General Public License for more details.
16+
* You should have received a copy of the GNU General Public License
17+
* along with this program. If not, see <https://www.gnu.org/licenses/>.
18+
* --------------------------------------------------------------------
19+
* Theme chooser module English translations of the application
20+
*
21+
* File version: 1.0
22+
* Last update: 10/25/2024
23+
*/
24+
25+
define ('MOD_Z4M_THEMECHOOSER_USER_PANEL_BUTTON_LABEL', 'Theme');
26+
define ('MOD_Z4M_THEMECHOOSER_MODAL_LIGHT_THEME_LABEL', 'Light');
27+
define ('MOD_Z4M_THEMECHOOSER_MODAL_DARK_THEME_LABEL', 'Dark');
28+
define ('MOD_Z4M_THEMECHOOSER_ACTION_STORE_OK', 'Favorite theme saved.');
29+
define ('MOD_Z4M_THEMECHOOSER_ACTION_STORE_ERROR', 'Failed to save favorite theme.');

‎mod/lang/locale_es.php

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
<?php
2+
/**
3+
* ZnetDK, Starter Web Application for rapid & easy development
4+
* See official website https://mobile.znetdk.fr
5+
* Copyright (C) 2024 Pascal MARTINEZ ([email protected])
6+
* License GNU GPL https://www.gnu.org/licenses/gpl-3.0.html GNU GPL
7+
* --------------------------------------------------------------------
8+
* This program is free software: you can redistribute it and/or modify
9+
* it under the terms of the GNU General Public License as published by
10+
* the Free Software Foundation, either version 3 of the License, or
11+
* (at your option) any later version.
12+
* This program is distributed in the hope that it will be useful,
13+
* but WITHOUT ANY WARRANTY; without even the implied warranty of
14+
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15+
* GNU General Public License for more details.
16+
* You should have received a copy of the GNU General Public License
17+
* along with this program. If not, see <https://www.gnu.org/licenses/>.
18+
* --------------------------------------------------------------------
19+
* Theme chooser module Spanish translations of the application
20+
*
21+
* File version: 1.0
22+
* Last update: 10/25/2024
23+
*/
24+
25+
define ('MOD_Z4M_THEMECHOOSER_USER_PANEL_BUTTON_LABEL', 'Tema');
26+
define ('MOD_Z4M_THEMECHOOSER_MODAL_LIGHT_THEME_LABEL', 'Claro');
27+
define ('MOD_Z4M_THEMECHOOSER_MODAL_DARK_THEME_LABEL', 'Oscuro');
28+
define ('MOD_Z4M_THEMECHOOSER_ACTION_STORE_OK', 'Preferencia de tema guardado.');
29+
define ('MOD_Z4M_THEMECHOOSER_ACTION_STORE_ERROR', 'No se pudo guardar el tema preferido.');

‎mod/lang/locale_fr.php

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
<?php
2+
/**
3+
* ZnetDK, Starter Web Application for rapid & easy development
4+
* See official website https://mobile.znetdk.fr
5+
* Copyright (C) 2024 Pascal MARTINEZ ([email protected])
6+
* License GNU GPL https://www.gnu.org/licenses/gpl-3.0.html GNU GPL
7+
* --------------------------------------------------------------------
8+
* This program is free software: you can redistribute it and/or modify
9+
* it under the terms of the GNU General Public License as published by
10+
* the Free Software Foundation, either version 3 of the License, or
11+
* (at your option) any later version.
12+
* This program is distributed in the hope that it will be useful,
13+
* but WITHOUT ANY WARRANTY; without even the implied warranty of
14+
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15+
* GNU General Public License for more details.
16+
* You should have received a copy of the GNU General Public License
17+
* along with this program. If not, see <https://www.gnu.org/licenses/>.
18+
* --------------------------------------------------------------------
19+
* Theme chooser module french translations of the application
20+
*
21+
* File version: 1.0
22+
* Last update: 10/25/2024
23+
*/
24+
25+
define ('MOD_Z4M_THEMECHOOSER_USER_PANEL_BUTTON_LABEL', 'Thème');
26+
define ('MOD_Z4M_THEMECHOOSER_MODAL_LIGHT_THEME_LABEL', 'Clair');
27+
define ('MOD_Z4M_THEMECHOOSER_MODAL_DARK_THEME_LABEL', 'Sombre');
28+
define ('MOD_Z4M_THEMECHOOSER_ACTION_STORE_OK', 'Préférence de thème enregistrée.');
29+
define ('MOD_Z4M_THEMECHOOSER_ACTION_STORE_ERROR', 'Echec d\'enregistrement du thème préféré.');

0 commit comments

Comments
 (0)