Skip to content

Commit be6af8f

Browse files
boneliferclaude
andcommitted
Add an optional introduction above the Knowledge Base index
The ACP configuration page gets a switch, a text box and a Markdown option for a short introduction shown under the Knowledge Base title, on the hierarchical index and the flat index. It is written in BBCode or Markdown and stored through the same article_text service as articles. Migration version_2_0_33 adds it switched off, holding the text kinerity/knowledgebase showed above its index, and switches it on on a board imported from kinerity, so its visitors keep seeing it. Tests: kb_intro_test.php (default text, display switch, saving BBCode and Markdown, emptying, the migration and its kinerity check). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent e00f2f6 commit be6af8f

17 files changed

Lines changed: 466 additions & 3 deletions

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,8 @@ The Knowledge Base follows each member's board style. It starts as a flat articl
3838
index (one list of every article, with a category dropdown); hierarchical category
3939
browsing and an optional colour stylesheet (a bundled one, or your own CSS file) are
4040
set on the same ACP page; see the [styling guide](docs/TODO/archive/styling/README.md).
41+
The same page can switch on a short introduction above the article index, written in
42+
BBCode or Markdown; it is off until you switch it on.
4143

4244
A search of the board also shows the matching articles in a **Knowledge Base** block above
4345
the forum results, with an **Also search the Knowledge Base** option in the advanced search.

‎adm/style/acp_knowledgebase_config.html‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,35 @@ <h1>{{ lang('ACP_KNOWLEDGE_BASE_CONFIGURE') }}</h1>
7575
<input name="hierarchical_index" id="hierarchical_index" type="checkbox" value="1" {{ HIERARCHICAL_INDEX_ON }}/>
7676
</dd>
7777
</dl>
78+
<dl>
79+
<dt>
80+
<label for="intro_enabled">{{ lang('KB_INTRO_ENABLE') }}{{ lang('COLON') }}</label><br>
81+
<span>{{ lang('KB_INTRO_ENABLE_EXPLAIN') }}</span>
82+
</dt>
83+
<dd>
84+
<input name="intro_enabled" id="intro_enabled" type="checkbox" value="1"
85+
onClick="document.getElementById('intro_options').style.display = this.checked ? '' : 'none';"
86+
{{ INTRO_ON }}/>
87+
</dd>
88+
</dl>
89+
<div id="intro_options" style="display: {{ INTRO_DISPLAY }};">
90+
<dl>
91+
<dt>
92+
<label for="intro_text">{{ lang('KB_INTRO_TEXT') }}{{ lang('COLON') }}</label><br>
93+
<span>{{ lang('KB_INTRO_TEXT_EXPLAIN') }}</span>
94+
</dt>
95+
<dd><textarea name="intro_text" id="intro_text" rows="6" cols="60">{{ INTRO_TEXT }}</textarea></dd>
96+
</dl>
97+
<dl>
98+
<dt>
99+
<label for="intro_markdown">{{ lang('KB_INTRO_MARKDOWN') }}{{ lang('COLON') }}</label><br>
100+
<span>{{ lang('KB_INTRO_MARKDOWN_EXPLAIN') }}</span>
101+
</dt>
102+
<dd>
103+
<input name="intro_markdown" id="intro_markdown" type="checkbox" value="1" {{ INTRO_MARKDOWN_ON }}/>
104+
</dd>
105+
</dl>
106+
</div>
78107
<dl>
79108
<dt>
80109
<label for="alt_style_enabled">{{ lang('KB_ALT_STYLE_ENABLE') }}{{ lang('COLON') }}</label><br>

‎config/services.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ services:
1818
- '@phpbbmodders.knowledgebase.inc'
1919
- '%tables.articles_table%'
2020
- '%tables.categories_table%'
21+
- '@phpbbmodders.knowledgebase.intro'
2122

2223
phpbbmodders.knowledgebase.controller.category:
2324
class: phpbbmodders\knowledgebase\controller\category
@@ -34,6 +35,7 @@ services:
3435
- '@phpbbmodders.knowledgebase.inc'
3536
- '%tables.articles_table%'
3637
- '%tables.categories_table%'
38+
- '@phpbbmodders.knowledgebase.intro'
3739

3840
phpbbmodders.knowledgebase.controller.recent_changes:
3941
class: phpbbmodders\knowledgebase\controller\recent_changes
@@ -262,6 +264,14 @@ services:
262264
# Argument order differs between 3.3.x and 4.0; the renderer class copes with either.
263265
- [configure_user, ['@user', '@config', '@auth']]
264266

267+
phpbbmodders.knowledgebase.intro:
268+
class: phpbbmodders\knowledgebase\inc\intro
269+
arguments:
270+
- '@config'
271+
- '@config_text'
272+
- '@phpbbmodders.knowledgebase.article_text'
273+
- '@template'
274+
265275
phpbbmodders.knowledgebase.article_text:
266276
class: phpbbmodders\knowledgebase\textformatter\article_text
267277
arguments:
@@ -346,6 +356,7 @@ services:
346356
- '%tables.kb_users_table%'
347357
- '%tables.kb_groups_table%'
348358
- '@phpbbmodders.knowledgebase.alternative_styles'
359+
- '@phpbbmodders.knowledgebase.intro'
349360

350361
phpbbmodders.knowledgebase.controller.set_order:
351362
class: phpbbmodders\knowledgebase\controller\set_order

‎controller/acp_controller.php‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@
3434
use phpbbmodders\knowledgebase\inc\field\kb_field_type_factory;
3535
use phpbbmodders\knowledgebase\inc\icon;
3636
use phpbbmodders\knowledgebase\inc\functions_kb;
37+
use phpbbmodders\knowledgebase\inc\intro;
3738
use phpbbmodders\knowledgebase\inc\upload_directory;
3839
use phpbbmodders\knowledgebase\search\kb_search_backend_factory;
3940

@@ -165,6 +166,9 @@ protected functions_kb $kb;
165166
* @param string $kb_groups_table
166167
* @param alternative_styles $alt_styles
167168
*/
169+
/** @var intro|null The index introduction text; optional so older callers still build */
170+
protected intro|null $intro;
171+
168172
public function __construct(
169173
driver_interface $db, config $config, db_text $config_text, helper $helper, manager $ext_manager,
170174
language $language, auth $auth, request_interface $request, template $template, user $user,
@@ -173,9 +177,10 @@ public function __construct(
173177
kb_field_type_factory $field_factory,
174178
string $phpbb_root_path, string $php_ext, string $articles_table, string $categories_table,
175179
string $logs_table, string $attachments_table, string $options_table, string $kb_users_table,
176-
string $kb_groups_table, alternative_styles $alt_styles
180+
string $kb_groups_table, alternative_styles $alt_styles, intro|null $intro = null
177181
)
178182
{
183+
$this->intro = $intro;
179184
$this->db = $db;
180185
$this->config = $config;
181186
$this->config_text = $config_text;
@@ -282,6 +287,10 @@ public function settings(): void
282287
'EXTGROUP_FILESIZE' => $max_filesize,
283288
'ADVANCED_FORM' => $announce_forum_id ? '' : 'none',
284289
'HIERARCHICAL_INDEX_ON' => $this->config['kb_hierarchical_index'] ? 'checked="checked"' : '',
290+
'INTRO_ON' => $this->intro && $this->intro->is_enabled() ? 'checked="checked"' : '',
291+
'INTRO_DISPLAY' => $this->intro && $this->intro->is_enabled() ? '' : 'none',
292+
'INTRO_TEXT' => $this->intro ? $this->intro->for_edit() : '',
293+
'INTRO_MARKDOWN_ON' => $this->intro && $this->intro->is_markdown() ? 'checked="checked"' : '',
285294
'ALT_STYLE_ON' => $this->config['kb_alt_style_enabled'] ? 'checked="checked"' : '',
286295
'ALT_STYLE_DISPLAY' => $this->config['kb_alt_style_enabled'] ? '' : 'none',
287296
'S_ALT_STYLE_OPTIONS' => $this->alternative_style_options((string) $this->config['kb_alt_style']),
@@ -360,6 +369,14 @@ protected function set_settings(): void
360369
$this->config->set('kb_font_icon', $kb_font_icon);
361370

362371
$this->config->set('kb_hierarchical_index', $this->request->variable('hierarchical_index', 0) ? 1 : 0);
372+
if ($this->intro)
373+
{
374+
$this->intro->save(
375+
(bool) $this->request->variable('intro_enabled', 0),
376+
utf8_normalize_nfc($this->request->variable('intro_text', '', true)),
377+
(bool) $this->request->variable('intro_markdown', 0)
378+
);
379+
}
363380
$this->config->set('kb_feed_format', $feed_format);
364381
$this->save_alternative_style();
365382
$this->save_announcement_forum();

‎controller/category.php‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222
use phpbb\template\template;
2323
use phpbb\user;
2424
use phpbbmodders\knowledgebase\inc\functions_kb;
25+
use phpbbmodders\knowledgebase\inc\intro;
2526

2627
class category
2728
{
@@ -77,12 +78,16 @@ protected functions_kb $kb;
7778
* @param string $articles_table
7879
* @param string $categories_table
7980
*/
81+
/** @var intro|null The index introduction text */
82+
protected intro|null $intro;
83+
8084
public function __construct(
8185
driver_interface $db, config $config, helper $helper, language $language, auth $auth,
8286
request_interface $request, template $template, user $user, pagination $pagination, functions_kb $kb,
83-
string $articles_table, string $categories_table
87+
string $articles_table, string $categories_table, intro|null $intro = null
8488
)
8589
{
90+
$this->intro = $intro;
8691
$this->db = $db;
8792
$this->config = $config;
8893
$this->helper = $helper;
@@ -473,6 +478,11 @@ public function cat(): \Symfony\Component\HttpFoundation\Response
473478
}
474479

475480
$this->kb->assign_nav_tabs_vars('index', $cat_id);
481+
// The flat index (all categories) is the Knowledge Base index in its default layout
482+
if ($flat_all)
483+
{
484+
$this->intro?->assign();
485+
}
476486

477487
return $this->helper->render('@phpbbmodders_knowledgebase/kb_cat_body.html', ($this->language->lang('LIBRARY') . ' &raquo; ' . $this->language->lang('CATEGORY')));
478488
}

‎controller/index.php‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222
use phpbb\template\template;
2323
use phpbb\user;
2424
use phpbbmodders\knowledgebase\inc\functions_kb;
25+
use phpbbmodders\knowledgebase\inc\intro;
2526

2627
class index
2728
{
@@ -77,12 +78,16 @@ protected functions_kb $kb;
7778
* @param string $articles_table
7879
* @param string $categories_table
7980
*/
81+
/** @var intro|null The index introduction text */
82+
protected intro|null $intro;
83+
8084
public function __construct(
8185
driver_interface $db, config $config, helper $helper, language $language, auth $auth,
8286
request_interface $request, template $template, user $user, pagination $pagination, functions_kb $kb,
83-
string $articles_table, string $categories_table
87+
string $articles_table, string $categories_table, intro|null $intro = null
8488
)
8589
{
90+
$this->intro = $intro;
8691
$this->db = $db;
8792
$this->config = $config;
8893
$this->helper = $helper;
@@ -178,6 +183,7 @@ public function main(): \Symfony\Component\HttpFoundation\Response
178183
]);
179184

180185
$this->kb->assign_nav_tabs_vars('index');
186+
$this->intro?->assign();
181187

182188
return $this->helper->render('@phpbbmodders_knowledgebase/kb_index_body.html', $this->language->lang('LIBRARY'));
183189
}

‎docs/testing.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1487,3 +1487,23 @@ is a separate piece of work, not part of this change.
14871487
**Not covered.** Boards upgraded from phpBB 3.3 to 4.0 with kinerity data (the sequence case is
14881488
covered by PHPUnit only); a custom style; kinerity versions before 1.2.1 on a board (1.0.x's missing
14891489
column is covered by PHPUnit only); MariaDB.
1490+
1491+
## Introduction text on the index - 11/12/2026
1492+
1493+
`inc/intro.php` shows an administrator's introduction under the Knowledge Base title, on the
1494+
hierarchical index and on the flat index (all categories). It is set on the ACP configuration page:
1495+
a switch, the text, and whether it is Markdown; BBCode, smilies and links work as in an article,
1496+
through the same `article_text` service. Migration `version_2_0_33` adds it switched off, holding
1497+
the text kinerity/knowledgebase showed, and switches it on on a board imported from kinerity.
1498+
1499+
`tests/kb_intro_test.php` covers the stored default text, nothing shown while switched off or empty,
1500+
saving BBCode and Markdown, emptying it, and the migration's steps and its kinerity check.
1501+
1502+
Claude ran the migration on the phpBB 3.3 PostgreSQL board imported from kinerity: it came up
1503+
switched on with kinerity's text, in the same place as on the kinerity board beside it. In the ACP,
1504+
the text was saved as BBCode (bold, a link, a smiley, `&` and quotes) and came back unchanged in the
1505+
editor, then as Markdown (bold, a link, inline code); both displayed formatted on the flat index. It
1506+
also showed on the hierarchical index, and nothing showed once it was switched off.
1507+
1508+
Not covered: a board that never ran kinerity in a browser (the migration's off-by-default path is
1509+
covered by PHPUnit), and other languages (the default text is English, as kinerity's was).

‎docs/upgrading-from-kinerity.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,11 @@ tables are kept, unchanged.
8585
A group or user that already has a setting for `u_kb_view` or `a_manage_kb`
8686
keeps it.
8787

88+
- **The introduction text** kinerity showed above its index. This extension's
89+
own introduction (Extensions → Knowledge Base → Configuration) starts out
90+
with kinerity's text and is switched on after an import, so visitors still
91+
see it. Edit it or switch it off there.
92+
8893
## What is removed
8994

9095
After the import, kinerity's permissions (with their settings in roles,

‎inc/intro.php‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
<?php
2+
/**
3+
*
4+
* Knowledge Base extension for the phpBB Forum Software package
5+
*
6+
* @copyright (c) 2026, phpBB Modders, https://www.phpbbmodders.com/
7+
* @license GNU General Public License, version 2 (GPL-2.0)
8+
*
9+
*/
10+
11+
namespace phpbbmodders\knowledgebase\inc;
12+
13+
use phpbb\config\config;
14+
use phpbb\config\db_text;
15+
use phpbb\template\template;
16+
use phpbbmodders\knowledgebase\textformatter\article_text;
17+
18+
/**
19+
* The introduction text shown at the top of the Knowledge Base index.
20+
*
21+
* An administrator switches it on and edits it on the ACP configuration page,
22+
* in BBCode or Markdown like an article. It is stored parsed, in the
23+
* kb_intro_text config_text entry, with its BBCode uid (kb_intro_uid) and
24+
* whether it is Markdown (kb_intro_markdown); kb_intro_enabled switches it on.
25+
* Migration version_2_0_33 adds it switched off, holding KB_INTRO_DEFAULT_TEXT
26+
* from language/<lang>/default_content.php (the text kinerity/knowledgebase
27+
* showed on its index) in the board's default language.
28+
*/
29+
class intro
30+
{
31+
protected config $config;
32+
protected db_text $config_text;
33+
protected article_text $article_text;
34+
protected template $template;
35+
36+
/**
37+
* @param config $config
38+
* @param db_text $config_text
39+
* @param article_text $article_text
40+
* @param template $template
41+
*/
42+
public function __construct(config $config, db_text $config_text, article_text $article_text, template $template)
43+
{
44+
$this->config = $config;
45+
$this->config_text = $config_text;
46+
$this->article_text = $article_text;
47+
$this->template = $template;
48+
}
49+
50+
/**
51+
* The stored form of plain text with no BBCode, as phpBB's parser would
52+
* store it, for the default text a migration writes.
53+
*
54+
* @param string $text Plain text, not escaped
55+
* @return string
56+
*/
57+
public static function stored_plain_text(string $text): string
58+
{
59+
return '<t>' . htmlspecialchars($text, ENT_COMPAT, 'UTF-8') . '</t>';
60+
}
61+
62+
/**
63+
* Whether the introduction is switched on.
64+
*
65+
* @return bool
66+
*/
67+
public function is_enabled(): bool
68+
{
69+
return !empty($this->config['kb_intro_enabled']);
70+
}
71+
72+
/**
73+
* Whether the stored text is Markdown.
74+
*
75+
* @return bool
76+
*/
77+
public function is_markdown(): bool
78+
{
79+
return !empty($this->config['kb_intro_markdown']);
80+
}
81+
82+
/**
83+
* Put the introduction on the page being built, when it is switched on
84+
* and not empty: KB_INTRO (HTML) and S_KB_INTRO.
85+
*
86+
* @return void
87+
*/
88+
public function assign(): void
89+
{
90+
$html = $this->is_enabled() ? $this->html() : '';
91+
92+
$this->template->assign_vars([
93+
'S_KB_INTRO' => $html !== '',
94+
'KB_INTRO' => $html,
95+
]);
96+
}
97+
98+
/**
99+
* The introduction as HTML, whether or not it is switched on.
100+
*
101+
* @return string Empty when there is no text
102+
*/
103+
public function html(): string
104+
{
105+
$stored = (string) $this->config_text->get('kb_intro_text');
106+
if (trim(strip_tags($stored)) === '')
107+
{
108+
return '';
109+
}
110+
111+
return $this->article_text->display($stored, (string) ($this->config['kb_intro_uid'] ?? ''), $this->is_markdown());
112+
}
113+
114+
/**
115+
* The introduction as the administrator typed it, escaped for a textarea.
116+
*
117+
* @return string
118+
*/
119+
public function for_edit(): string
120+
{
121+
return $this->article_text->for_edit((string) $this->config_text->get('kb_intro_text'));
122+
}
123+
124+
/**
125+
* Save the introduction from the ACP form.
126+
*
127+
* @param bool $enabled
128+
* @param string $text Submitted text, escaped by the request layer
129+
* @param bool $markdown True to parse it as Markdown, false for BBCode
130+
* @return void
131+
*/
132+
public function save(bool $enabled, string $text, bool $markdown): void
133+
{
134+
$uid = $bitfield = '';
135+
$options = 0;
136+
if (trim($text) !== '')
137+
{
138+
$this->article_text->store($text, $markdown, $uid, $bitfield, $options);
139+
}
140+
else
141+
{
142+
$text = '';
143+
}
144+
145+
$this->config_text->set('kb_intro_text', $text);
146+
$this->config->set('kb_intro_uid', (string) $uid);
147+
$this->config->set('kb_intro_markdown', $markdown ? 1 : 0);
148+
$this->config->set('kb_intro_enabled', $enabled ? 1 : 0);
149+
}
150+
}

0 commit comments

Comments
 (0)