dolibarr 25.0.0-alpha
documentation.class.php
1<?php
2/* Copyright (C) 2024 Anthony Damhet <a.damhet@progiseize.fr>
3 * Copyright (C) 2024 Frédéric France <frederic.france@free.fr>
4 * Copyright (C) 2026 MDW <mdeweerd@users.noreply.github.com>
5 *
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 3 of the License, or
9 * (at your option) any later version.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
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
30{
36 public $view = array();
37
43 public $menu = array();
44
50 public $summary = array();
51
55 public $db;
56
60 public $baseUrl = 'admin/tools/ui';
61
68 public function __construct(DoliDB $db)
69 {
70 $this->db = $db;
71
72 // https://www.figma.com/community/file/1393171578760389765/dolibarr-ui-ux-kit
73
74 // Menu Constructor
75 $this->setMenu();
76 }
77
83 private function setMenu()
84 {
85 global $hookmanager;
86
87 $hookmanager->initHooks(array('uidocumentation'));
88
89 // Go back to Dolibarr
90 $this->menu['BackToDolibarr'] = array(
91 'url' => dol_buildpath('modulebuilder/index.php', 1),
92 'icon' => 'fas fa-arrow-left',
93 'submenu' => array(),
94 );
95
96 // Home for Ui documentation
97 $this->menu['DocumentationHome'] = array(
98 'url' => dol_buildpath($this->baseUrl.'/index.php', 1),
99 'icon' => 'fas fa-book',
100 'submenu' => array(),
101 );
102
103 // Components
104 $this->menu['Components'] = array(
105 'url' => dol_buildpath($this->baseUrl.'/components/index.php', 1),
106 'icon' => 'fas fa-th-large',
107 'submenu' => array(
108 'Badges' => array(
109 'url' => dol_buildpath($this->baseUrl.'/components/badges.php', 1),
110 'icon' => 'fas fa-certificate',
111 'submenu' => array(),
112 'summary' => array(
113 'DocBasicUsage' => '#badgesection-basicusage',
114 'DocBadgeContextualVariations' => '#badgesection-contextvariations',
115 'DocBadgeDefaultStatus' => '#badgesection-defaultstatus',
116 'DocBadgePillBadges' => '#badgesection-pill',
117 'DocBadgeDotBadges' => '#badgesection-dot',
118 'DocBadgeLinks' => '#badgesection-links',
119 'DocBadgeHelper' => '#badgesection-dolgetbadge'
120 ),
121 ),
122 'Buttons' => array(
123 'url' => dol_buildpath($this->baseUrl.'/components/buttons.php', 1),
124 'icon' => 'fas fa-mouse',
125 'submenu' => array(),
126 'summary' => array(
127 'DocBasicUsage' => '#buttonsection-basicusage',
128 'DocButtonModal' => '#buttonsection-modals',
129 'DocButtonSubmenu' => '#buttonsection-submenu',
130 ),
131 ),
132 'Icons' => array(
133 'url' => dol_buildpath($this->baseUrl.'/components/icons.php', 1),
134 'icon' => 'far fa-flag',
135 'submenu' => array(),
136 'summary' => array(
137 'DocIconsList' => '#img-picto-section-list',
138 'DocIconsFontAwesomeList' => '#icon-section-list',
139 ),
140 ),
141 'Progress' => array(
142 'url' => dol_buildpath($this->baseUrl.'/components/progress-bars.php', 1),
143 'icon' => 'fas fa-battery-half',
144 'submenu' => array(),
145 'summary' => array(
146 'DocBasicUsage' => '#progresse-section-basic-usage',
147 'DocColorVariants' => '#progress-section-color',
148 'DocStripedVariants' => '#progresse-section-stripped',
149 ),
150 ),
151 'Event Message' => array(
152 'url' => dol_buildpath($this->baseUrl.'/components/event-message.php', 1),
153 'icon' => 'fas fa-comments',
154 'submenu' => array(),
155 'summary' => array(
156 'DocBasicUsage' => '#seteventmessagesection-basicusage',
157 'DocSetEventMessageContextualVariations' => '#seteventmessagesection-contextvariations',
158 'DocSetEventMessageJsContext' => '#titlesection-tool-seteventmessage',
159 )
160 ),
161 'Inputs' => array(
162 'url' => dol_buildpath($this->baseUrl.'/components/inputs.php', 1),
163 'icon' => 'far fa-edit',
164 'submenu' => array(),
165 'summary' => array(
166 'DocBasicUsage' => '#setinputssection-basicusage',
167 'DocHelperFunctionsInputUsage' => '#setinputssection-helperfunctions',
168 'DocHelperFunctionsGetSearchFilterToolInput' => '#setinputssection-getSearchFilterToolInput',
169 )
170 ),
171 'ExperimentalUxInputAjaxFeedback' => array(
172 'url' => dol_buildpath($this->baseUrl.'/content/input-feedback.php', 1),
173 'icon' => 'far fa-share-square',
174 'submenu' => array(),
175 'summary' => array(),
176 ),
177 ),
178 );
179
180 // Elements
181 $this->menu['Content'] = array(
182 'url' => dol_buildpath($this->baseUrl.'/content/index.php', 1),
183 'icon' => 'far fa-file-alt',
184 'submenu' => array(
185 'Titles' => array(
186 'url' => dol_buildpath('admin/tools/ui/content/titles.php', 1),
187 'icon' => 'fas fa-heading',
188 'submenu' => array(),
189 'summary' => array(
190 'DocBasicUsage' => '#titlesection-basicusage',
191 'DocTitleWithFilters' => '#titlesection-withfilters',
192 ),
193 ),
194 'Tables' => array(
195 'url' => dol_buildpath('admin/tools/ui/content/tables.php', 1),
196 'icon' => 'fas fa-table',
197 'submenu' => array(),
198 'summary' => array(
199 'DocBasicUsage' => '#tablesection-basicusage',
200 'DocTableWithFilters' => '#tablesection-withfilters',
201 'DocTableBeforeFilters' => '#tablesection-beforefilters',
202 'DocTableCSSClass' => '#tablesection-cssclasses',
203 ),
204 ),
205
206 'TableRowIntuitiveSelect' => array(
207 'url' => dol_buildpath($this->baseUrl.'/content/intuitive-table-row-select.php', 1),
208 'icon' => 'far fa-check-square',
209 'submenu' => array(),
210 'summary' => array(),
211 ),
212
213 'FreezeTooltip' => array(
214 'url' => dol_buildpath($this->baseUrl.'/content/freeze-tooltip.php', 1),
215 'icon' => 'far fa-comment',
216 'submenu' => array(),
217 'summary' => array(),
218 ),
219 )
220 );
221
222 // Elements
223 $this->menu['Resources'] = array(
224 'url' => dol_buildpath($this->baseUrl.'/resources/index.php', 1),
225 'icon' => 'fas fa-wrench',
226 'submenu' => array(
227 'Contributing' => array(
228 'url' => dol_buildpath($this->baseUrl.'/resources/contributing.php', 1),
229 'icon' => 'fas fa-code',
230 'submenu' => array(),
231 'summary' => array(
232 'DocContributeStep1' => '#contributesection-step1',
233 'DocContributeStep2' => '#contributesection-step2',
234 'DocContributeStep3' => '#contributesection-step3',
235 ),
236 ),
237 )
238 );
239
240 // Elements
241 $this->menu['UxDolibarrContext'] = array(
242 'url' => dol_buildpath($this->baseUrl.'/dolibarr-context/index.php', 1),
243 'icon' => 'fab fa-fort-awesome',
244 'submenu' => array(
245 'UxDolibarrContextHowItWork' => array(
246 'url' => dol_buildpath($this->baseUrl.'/dolibarr-context/index.php', 1),
247 'icon' => 'fab fa-fort-awesome',
248 'submenu' => array(),
249 'summary' => array(
250 'Introduction' => '#titlesection-basicusage',
251 'ConsoleHelp' => '#titlesection-console-help',
252 'JSDolibarrhooks' => '#titlesection-hooks',
253 'JSDolibarrhooksReadyVsInit' => '#titlesection-event-init-vs-ready',
254 'JSDolibarrhooksLateScripts' => '#titlesection-late-scripts',
255 'JSDolibarrAwaitHooks' => '#titlesection-await-hooks',
256 'JSDolibarrhooksAjaxSpecial' => '#titlesection-dom-initnewcontent',
257 'ExampleOfCreatingNewContextTool' => '#titlesection-create-tool-example',
258 'JSContextCompatAndDeprecations' => '#titlesection-compat',
259 'SetEventMessageTool' => '#titlesection-tool-seteventmessage',
260 'FetchTool' => '#titlesection-tool-fetch',
261 'SetAndUseContextVars' => '#titlesection-contextvars',
262 'AddContextVarsFromModule' => '#titlesection-contextvars-module',
263 ),
264 ),
265 'UxDolibarrContextLangsTool' => array(
266 'url' => dol_buildpath($this->baseUrl.'/dolibarr-context/langs-tool.php', 1),
267 'icon' => 'far fa-flag',
268 'submenu' => array(),
269 'summary' => array(),
270 ),
271 'UxDolibarrContextKnowsHooks' => array(
272 'url' => dol_buildpath($this->baseUrl.'/dolibarr-context/knows-hooks.php', 1),
273 'icon' => 'fa fa-anchor',
274 'submenu' => array(),
275 'summary' => array(),
276 ),
277 )
278 );
279
280 // Elements
281 $this->menu['ExperimentalUx'] = array(
282 'url' => dol_buildpath($this->baseUrl.'/experimental/index.php', 1),
283 'icon' => 'fas fa-flask',
284 'submenu' => array(
285 'ExperimentalUxIntroductionMenu' => array(
286 'url' => dol_buildpath($this->baseUrl.'/experimental/index.php', 1),
287 'icon' => 'fas fa-flask',
288 'submenu' => array(),
289 'summary' => array(
290 'Index' => '#top',
291 'ExperimentalUxIntroductionTitle' => '#experimental-ux-introduction',
292 'ExperimentalUxContributionTitle' => '#experimental-ux-contribution',
293 ),
294 ),
295 'UxMenuTooltipTheme' => array(
296 'url' => dol_buildpath($this->baseUrl.'/experimental/tooltip-themes/index.php', 1),
297 'icon' => 'fas fa-comment',
298 'submenu' => array(),
299 'summary' => array(
300 'Introduction' => '#ux-introduction',
301 'TooltipThemesAndOrientation' => '#tooltip-themes',),
302 ),
303 )
304 );
305
306 $parameters = array(
307 'baseUrl' => $this->baseUrl,
308 );
309 $action = '';
310
311 $reshook = $hookmanager->executeHooks('setMenu', $parameters, $this, $action);
312 if ($reshook < 0) {
313 return false;
314 }
315
316 return true;
317 }
318
328 public function docHeader($title = '', $arrayofjs = [], $arrayofcss = [], $hidenavmenu = '')
329 {
330 global $langs;
331 $title = (!empty($title)) ? dol_escape_htmltag($title) : $langs->trans('Documentation');
332
333 $arrayofcss[] = 'admin/tools/ui/css/documentation.css';
334
335 top_htmlhead('', $title, 0, 0, $arrayofjs, $arrayofcss);
336
337 print '<body class="dolibarr-doc'.($hidenavmenu ? "-bis" : "").'">';
338 }
339
344 public function docFooter()
345 {
346 global $langs;
347
348 // DIV FOR SCROLL ANIMATION
349 print '<div id="documentation-scrollwrapper">';
350 print '<div id="documentation-scroll"></div>';
351 print '</div>';
352
353 // JS
354 print '<script src="'.dol_buildpath('admin/tools/ui/js/documentation.js', 1).'"></script>';
355 print '<script src="'.DOL_URL_ROOT.'/core/js/lib_foot.js.php?lang='.$langs->defaultlang.'"></script>';
356
357 print '</body>';
358 print '</html>';
359
361 }
362
368 public function showSidebar()
369 {
370 print '<div class="doc-sidebar">';
371
372 // LOGO
373 print '<div class="sidebar-logo">';
374 if (is_readable(DOL_DOCUMENT_ROOT.'/theme/dolibarr_logo.svg')) {
375 $urllogo = DOL_URL_ROOT.'/theme/dolibarr_logo.svg';
376 print '<img src="'.$urllogo.'" />';
377 }
378 print '</div>';
379
380 // NAVIGATION
381 print '<nav>';
382 if (!empty($this->menu)) {
383 $this->displayMenu($this->menu);
384 }
385 print '</nav>';
386
387 print '</div>';
388 }
389
397 private function displayMenu($menu, $level = 0)
398 {
399 global $langs;
400 $level++;
401
402 print '<ul>';
403 foreach ($menu as $key => $item) {
404 $levelclass = (!empty($item['submenu'])) ? 'li-withsubmenu' : '';
405 $levelclass .= (in_array($key, $this->view)) ? ' active' : '';
406 $levelclass .= ($key == 'BackToDolibarr') ? ' li-withseparator' : '';
407
408 print '<li class="'.trim($levelclass).' level-'.$level.'">';
409 print '<a href="'.$item['url'].'" class="'.((!empty($item['submenu'])) ? 'link-withsubmenu' : '').'">';
410 print ((!empty($item['icon'])) ? '<i class="menu-icon '.$item['icon'].' pictofixedwidth" aria-hidden="true"></i>' : '');
411 print '<span class="label">'.$langs->transnoentities($key).'</span>';
412 print ((!empty($item['submenu'])) ? '<i class="submenu-toggle fas fa-chevron-right" aria-hidden="true"></i>' : '');
413 print '</a>';
414 if (!empty($item['submenu'])) {
415 $this->displayMenu($item['submenu'], $level); // Recursive call to show submenu
416 }
417 echo '</li>';
418 }
419 print '</ul>';
420 }
421
427 public function showBreadcrumb()
428 {
429 global $langs;
430
431 print '<nav class="doc-breadcrumbs">';
432 print '<ul>';
433 print '<li class="breadcrumb-item"><a href="'.$this->menu['DocumentationHome']['url'].'"><i class="'.$this->menu['DocumentationHome']['icon'].'" aria-hidden="true"></i></a></li>';
434 if (!empty($this->view)) {
435 $nb_entries = count($this->view);
436 $i = 0;
437
438 $menu_entry = $this->menu;
439 foreach ($this->view as $page) {
440 $i++;
441 if ($i < $nb_entries && isset($menu_entry[$page])) {
442 print '<li class="breadcrumb-item"><a href="'.$menu_entry[$page]['url'].'">'.$langs->transnoentities($page).'</a></li>';
443 $menu_entry = $menu_entry[$page]['submenu'];
444 } else {
445 print '<li class="breadcrumb-item">'.$langs->transnoentities($page).'</li>';
446 }
447 }
448 } else {
449 print '<li class="breadcrumb-item">'.$langs->trans('Documentation').'</li>';
450 }
451 print '</ul>';
452 print '</nav>';
453 }
454
462 public function showSummary($showsubmenu = 1, $showsubmenu_summary = 1)
463 {
464 global $langs;
465
466 $i = 0;
467 $menu_entry = [];
468 if (!empty($this->view)) {
469 // Set the correct menu depth (level)
470 foreach ($this->view as $view) {
471 $i++;
472 if ($i == 1) {
473 $menu_entry = $this->menu[$view] ?? [];
474 } else {
475 $menu_entry = $menu_entry['submenu'][$view] ?? [];
476 }
477 }
478 }
479
480 if (!empty($menu_entry['summary']) || (!empty($menu_entry['submenu']) && $showsubmenu)) {
481 // Summary with links to sections of the page: shown in a sticky column on large screens (see documentation.css and documentation.js)
482 $hasanchors = false;
483 foreach ($menu_entry['summary'] ?? [] as $summary_link) {
484 if (strpos($summary_link, '#') === 0) {
485 $hasanchors = true;
486 break;
487 }
488 }
489
490 print '<div class="summary-wrapper'.($hasanchors ? ' summary-toc' : '').'" data-toc-title="'.dolPrintHTMLForAttribute($langs->transnoentities('DocPageSummary')).'" data-toc-backtop="'.dolPrintHTMLForAttribute($langs->transnoentities('DocBackToTop')).'">';
491 $this->displaySummary($menu_entry);
492 print '</div>';
493 }
494 }
495
496
506 public function displaySummary($menu, $level = 0, $showsubmenu = 1, $showsubmenu_summary = 1)
507 {
508 global $langs;
509
510 $level++;
511 print '<ul class="documentation-summary level-'.$level.'"">';
512
513 if (!empty($menu['summary'])) {
514 foreach ($menu['summary'] as $summary_label => $summary_link) {
515 /*
516 if ($summary_link[0] == '#') {
517 $tmp_summary_link = $menu['url'];
518 if (GETPOSTINT('hidenavmenu')) {
519 $tmp_summary_link .= (strpos($tmp_summary_link, '?') === false ? '?' : '&').'hidenavmenu=1';
520 }
521 if (GETPOSTINT('displayMode')) {
522 $tmp_summary_link .= (strpos($tmp_summary_link, '?') === false ? '?' : '&').'displayMode=1';
523 }
524 $summary_link = $tmp_summary_link;
525 }
526 */
527
528 print '<li><a href="'.$summary_link.'">'.$langs->trans($summary_label).'</a></li>';
529 }
530 }
531
532 if ($showsubmenu && !empty($menu['submenu'])) {
533 foreach ($menu['submenu'] as $key => $item) {
534 print '<li class="summary-title ">';
535
536 if (!empty($item['url'])) {
537 print '<h3 class="level-'.$level.'"><a href="'.dolBuildUrl($item['url']).'" >'.$langs->trans($key).'</a></h3>';
538 } else {
539 print '<h3 class="level-'.$level.'">'.$langs->trans($key).'</h3>';
540 }
541
542 if ($showsubmenu_summary) {
543 $this->displaySummary($item, $level);
544 }
545 print '</li>';
546 }
547 }
548 print '</ul>';
549 }
550
558 public function showCode($lines = array(), $option = 'html')
559 {
560 require_once DOL_DOCUMENT_ROOT . '/core/class/doleditor.class.php';
561 print '<div class="documentation-code">';
562
563 if (isset($lines[0])) {
564 if ($option === 'html' && strpos(strtolower($lines[0]), '<!doctype') === false) {
565 array_unshift($lines, '<!DOCTYPE html>', '');
566 }
567 }
568
569 $content = implode("\n", $lines) . "\n";
570 $doleditor = new DolEditor(md5($content), $content, '', 0, 'Basic', 'In', true, false, 'ace', 0, '99%', 1);
571 print $doleditor->Create(1, '', false, '', $option);
572 print '</div>';
573 }
574
575
584 static public function generateLoremIpsum($paragraphCount = 3, $wordsPerParagraph = 50, $html = true)
585 {
586 $baseText = "Lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor incididunt ut labore et dolore magna aliqua Ut enim ad minim veniam quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur Excepteur sint occaecat cupidatat non proident sunt in culpa qui officia deserunt mollit anim id est laborum";
587
588 $words = explode(" ", $baseText);
589 $paragraphs = [];
590
591 for ($p = 0; $p < $paragraphCount; $p++) {
592 $sentence = [];
593 for ($i = 0; $i < $wordsPerParagraph; $i++) {
594 $word = $words[array_rand($words)];
595
596 // Randomly add a comma
597 if ($i > 2 && rand(0, 10) > 8) {
598 $word .= ",";
599 }
600
601 $sentence[] = $word;
602 }
603
604 $paragraphText = ucfirst(implode(" ", $sentence)) . ".";
605 if ($html) {
606 $paragraphText = "<p>$paragraphText</p>";
607 }
608 $paragraphs[] = $paragraphText;
609 }
610
611 return implode($html ? "\n" : "\n\n", $paragraphs);
612 }
613}
Class to manage UI documentation.
showBreadcrumb()
Output breadcrumb.
displayMenu($menu, $level=0)
Recursive function to set Menu.
showSummary($showsubmenu=1, $showsubmenu_summary=1)
Output summary.
docFooter()
Output close body + html.
showCode($lines=array(), $option='html')
Output a View Code area.
docHeader($title='', $arrayofjs=[], $arrayofcss=[], $hidenavmenu='')
Output header + body.
showSidebar()
Output sidebar.
__construct(DoliDB $db)
Constructor.
setMenu()
Set Documentation Menu.
static generateLoremIpsum($paragraphCount=3, $wordsPerParagraph=50, $html=true)
Generate lorem ipsum.
displaySummary($menu, $level=0, $showsubmenu=1, $showsubmenu_summary=1)
Recursive function for Automatic Summary.
Class to manage a WYSIWYG editor.
Class to manage Dolibarr database access.
dolBuildUrl($url, $params=[], $addtoken=false, $anchor='')
Return path of url.
dol_buildpath($path, $type=0, $returnemptyifnotfound=0)
Return path of url or filesystem.
dol_htmloutput_events($disabledoutputofmessages=0)
Print formatted messages to output (Used to show messages on html output).
dol_escape_htmltag($stringtoescape, $keepb=0, $keepn=0, $noescapetags='', $escapeonlyhtmltags=0, $cleanalsojavascript=0)
Definition html.lib.php:183
top_htmlhead($head, $title='', $disablejs=0, $disablehead=0, $arrayofjs=array(), $arrayofcss=array(), $disableforlogin=0, $disablenofollow=0, $disablenoindex=0)
Output html header of a page.