added help files for YaCy UI web pages

1 files changed, 94 insertions, 0 deletions

diff --git a/help/ConfigSearchBox.md b/help/ConfigSearchBox.md
new file mode 100644
index 000000000..012d3c900
--- /dev/null
+++ b/help/ConfigSearchBox.md
@@ -0,0 +1,94 @@
+---
+page: htroot/ConfigSearchBox.html
+help: help/ConfigSearchBox.md
+title: Integration of a Search Box
+package: configuration-administration
+access: mixed
+kind: search-page
+backend_java: source/net/yacy/htroot/ConfigSearchBox.java
+---
+
+# Integration of a Search Box
+
+## Purpose
+
+Integration of a Search Box generates embeddable search-box code for another website. It helps turn this YaCy peer into the search backend for a page that lives somewhere else.
+
+Use it when visitors should type a query on an external site and receive results from `yacysearch.html` on this peer.
+
+## What You Can Do Here
+
+- Generate or inspect the HTML snippet for an external search box.
+- Understand that the generated form submits to `yacysearch.html`, so the real search parameters are the same as the search page.
+- Use the snippet only after choosing the target peer address and expected result behavior.
+
+## Page Architecture
+
+This page is an integration helper. It shows the HTML form code for a search box and demonstrates the target request that the form will send to `yacysearch.html`. The controls on this page are not a separate search engine; they are a compact front door into the normal YaCy search endpoint.
+
+## Correct Use
+
+Use the generated code as a template, then adapt the surrounding site HTML outside YaCy. Keep the form action pointed at the YaCy peer that should answer searches, and keep the query field named `query`. If the external page should search only a collection or site, add the same search parameters documented for `yacysearch.html`.
+
+## Access And Safety
+
+The page may be visible, but the backend performs authentication checks for protected actions.
+
+Protected related endpoint(s): `/yacysearch.html`.
+
+Backend checks: administrator authentication, user authentication.
+
+## Automation And API
+
+Page backend: `source/net/yacy/htroot/ConfigSearchBox.java`.
+
+| Endpoint | Method | Access | Backend |
+| --- | --- | --- | --- |
+| `/yacysearch.html` | `GET` | mixed | `source/net/yacy/htroot/yacysearch.java` |
+
+### Parameter Guide
+
+The table explains values that an agent or script must set deliberately. Parameters not relevant to a task should be omitted or left at the page default.
+
+| Parameter | Meaning and valid values | Care |
+| --- | --- | --- |
+| `query` | Search text. Use ordinary search terms, quoted phrases where supported by YaCy query parsing, and optional YaCy modifiers such as collection filters when you intentionally need them. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. |
+| `auth` | Requests authentication-aware behavior when the endpoint supports user-specific or protected actions. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
+| `callback` | JSONP callback name for legacy script clients. Leave empty for normal HTML or JSON-style use. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
+| `collection` | Collection name. Use it to group crawled or imported documents and to search or manage that group later. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
+| `constraint` | Encoded YaCy bitfield constraint. Leave it empty unless you are replaying a URL generated by YaCy itself. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
+| `contentdom` | Content domain filter. Common values are `all`, `text`, `image`, `audio`, `video`, and `app`; use it to ask for web pages, media, or application documents deliberately. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
+| `count` | SRU-style result count. It is an alternative to `maximumRecords` on search endpoints. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. |
+| `deleteref` | URL hash/reference selected for deletion from results. Use only with administrator intent and an exact known reference. | Can remove data, stop work, expose access, or make a broad operational change. Use only with explicit confirmation and an exact target. |
+| `focus` | Browser presentation flag controlling whether the search input receives focus. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
+| `indexof` | Interprets the query as an index-of style request when supported. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
+| `lr` | Language filter, usually a two-letter code such as `de`, `fr`, or `en` when the page supports language-restricted search. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
+| `maximumRecords` | Maximum number of results to return on one page. Use a modest value for interactive use; larger values are for controlled scripts. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. |
+| `nav` | Navigator/facet selection for search results. `all` requests the normal set; narrower values reduce displayed facets. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
+| `offset` | Zero-based result offset for pagination. | Read-only pagination control; use it to request later result pages. |
+| `prefermaskfilter` | Regular-expression URL preference. Matching results are favored without excluding all others. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. |
+| `recommendref` | URL hash/reference selected for recommendation. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
+| `resortCachedResults` | Requests resorting of a cached search event instead of starting a fully fresh result event. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. |
+| `resource` | Search source. `local` searches this peer index; `global` may use the YaCy network when the peer and configuration allow it. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
+| `resource-switch` | Browser control for switching between local and global search. For direct calls use `resource=local` or `resource=global`. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
+| `rows` | Rows requested by API-style clients. It is another result-count alias on search endpoints. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. |
+| `search` | Alternative search text parameter accepted by some search endpoints; prefer `query` on browser search pages unless reproducing an existing URL. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
+| `startRecord` | First result record for pagination; accepted as an alternative to `offset` on search endpoints. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
+| `strictContentDom` | When true, YaCy enforces the selected content domain more strictly instead of using it mainly for presentation. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
+| `timezoneOffset` | Client timezone offset in minutes. YaCy uses it for date display or schedule calculations. | Read-only request context for date handling. |
+| `urlmaskfilter` | Regular-expression URL filter for search results. Use `.*` for no restriction; use a precise host/path expression to search inside a site or section. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. |
+| `verify` | Snippet/cache verification strategy. Typical values are `iffresh`, `ifexist`, `cacheonly`, `nocache`, and `false`; choose according to whether freshness or speed matters more. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
+
+Example request shape:
+
+```http
+GET /yacysearch.html?query=...&maximumRecords=...&resource=...&contentdom=...&Enter=...
+```
+
+## What To Expect
+
+The page provides an embeddable snippet or demonstration form. The actual user search happens later when a visitor submits the form and YaCy receives a `yacysearch.html` request.
+
+## Related Pages
+
+- Related configuration work is usually reached from `ConfigBasic.html`, `Settings_p.html`, or the adjacent configuration page in the administration menu.