diff --git a/de/15.8/dev/theme-development.rst b/de/15.8/dev/theme-development.rst index 6a2393f9..ebdf776e 100644 --- a/de/15.8/dev/theme-development.rst +++ b/de/15.8/dev/theme-development.rst @@ -1,131 +1,350 @@ ================================== -Theme-Entwicklungsanleitung +Theme-Entwicklungsleitfaden ================================== Übersicht ========= -Mit dem Theme-System von |Fess| konnen Sie das Design der Suchoberflache anpassen. -Themes konnen als Plugins verteilt werden, und Sie konnen zwischen mehreren Themes wechseln. +Mit |Fess| können Sie das Design der Suchoberfläche auf die folgenden +zwei Arten anpassen. -Theme-Struktur -============== +Statisches Theme (Static Theme) + Dieser Mechanismus wurde in |Fess| 15.7 eingeführt. Das Theme wird + als ZIP-Datei verteilt, über die Administrationsoberfläche + hochgeladen und aktiviert. Das Theme selbst ist eine eigenständige + SPA (Single-Page-Anwendung), die die ``/api/v2/*`` API nutzt, und + ist nicht von den JSPs des |Fess|-Kerns abhängig. Für die + Neuentwicklung von Themes wird diese Methode empfohlen. + +JAR-Theme-Plugin (Legacy) + Dies ist der herkömmliche Plugin-Typ, der ``view`` / ``css`` / + ``js`` / ``images`` überschreibt. Es wird als JAR gebaut und als + Plugin installiert. Es wird verwendet, wenn Teile der bestehenden + JSP-basierten Oberfläche ersetzt werden sollen. + +.. note:: + + Statische Themes stehen ab |Fess| 15.7 zur Verfügung. Wenn Sie + Version 15.6 oder älter einsetzen, verwenden Sie ein + JAR-Theme-Plugin. Wie Sie JSP, CSS und Bilder der Suchoberfläche + direkt über die Administrationsoberfläche bearbeiten, erfahren Sie + unter :doc:`../admin/design-guide`. + +Statisches Theme +================ + +Ein statisches Theme ist eine Sammlung statischer Ressourcen, die das +``theme.yml``-Manifest und ``index.html`` enthält. Das Theme selbst +wird als Frontend-Anwendung implementiert, die die ``/api/v2/*`` API +von |Fess| aufruft. + +Struktur +-------- + +Ein statisches Theme hat die folgende Verzeichnisstruktur. :: - fess-theme-example/ - ├── pom.xml - └── src/main/resources/ - └── theme/example/ - ├── css/ - │ ├── style.css - │ └── custom.css - ├── js/ - │ └── custom.js - ├── images/ - │ └── logo.png - └── templates/ - └── search.html - -Grundlegendes Theme erstellen -============================= - -CSS-Anpassung -------------- - -``css/style.css``: - -.. code-block:: css - - /* Header-Anpassung */ - .navbar { - background-color: #1a237e; - } - - /* Suchfeld-Stil */ - .search-box { - border-radius: 25px; - box-shadow: 0 2px 5px rgba(0,0,0,0.2); - } - - /* Suchergebnis-Stil */ - .search-result-item { - border-left: 3px solid #1a237e; - padding-left: 15px; - } - -Logo andern ------------ + example/ + ├── theme.yml # Manifest (erforderlich) + ├── index.html # Einstiegs-HTML der SPA + ├── assets/ # Statische Ressourcen wie JavaScript und CSS + │ └── styles.css + ├── i18n/ # Mehrsprachige Meldungen (messages..json) + │ └── messages.en.json + ├── help/ # Hilfedefinitionen (.json) + │ └── en.json + └── thumbnail.png # Vorschaubild (optional) + +Manifest (theme.yml) +--------------------- + +``theme.yml`` ist das erforderliche Manifest, das im Stammverzeichnis +des ZIP abgelegt wird. Im Folgenden sehen Sie ein Beispiel für die +minimale Konfiguration. + +.. code-block:: yaml + + apiVersion: fess.codelibs.org/v1 + kind: StaticTheme + name: example + displayName: "Example Theme" + version: "1.0.0" + minFessVersion: "15.7" + entry: index.html + spaFallback: true + +Die folgenden Felder können angegeben werden. + +.. list-table:: + :header-rows: 1 + :widths: 22 12 66 + + * - Feld + - Erforderlich + - Beschreibung + * - ``apiVersion`` + - Erforderlich + - Fester Wert ``fess.codelibs.org/v1``. + * - ``kind`` + - Erforderlich + - Fester Wert ``StaticTheme``. + * - ``name`` + - Erforderlich + - Theme-Name. Muss dem Muster ``^[a-z0-9][a-z0-9_-]{0,63}$`` + entsprechen. Wird als Verzeichnisname des Themes verwendet, der + unter ``themes/`` entpackt wird (beim Hochladen wird dieser Name + automatisch aus ``name`` bestimmt), sowie für die + Auslieferungs-URL (``/themes//``). + * - ``displayName`` + - Erforderlich + - Der in der Administrationsoberfläche angezeigte Name. + * - ``version`` + - Erforderlich + - Format nach Semantic Versioning (Beispiel: ``1.0.0``, + ``1.2.3-beta.1``). + * - ``author`` + - Optional + - Name des Autors. + * - ``description`` + - Optional + - Beschreibung des Themes. + * - ``license`` + - Optional + - Lizenz. + * - ``homepage`` + - Optional + - URL der Homepage. + * - ``minFessVersion`` + - Optional + - Die minimale |Fess|-Version, die vom Theme unterstützt wird. + * - ``supportedLocales`` + - Optional + - Liste der unterstützten Locales (Beispiel: ``[en, ja, de]``). + * - ``entry`` + - Optional + - Einstiegs-HTML der SPA. Standardwert ist ``index.html``. + * - ``spaFallback`` + - Optional + - Aktivierung/Deaktivierung des SPA-Fallbacks. Standardwert ist + ``true``. + +.. note:: + + Beim Hochladen als ZIP wird der Name des Zielverzeichnisses + automatisch aus ``name`` bestimmt. Wenn Sie ein Theme manuell im + Verzeichnis ``themes/`` ablegen, muss der Verzeichnisname mit + ``name`` übereinstimmen. Themes, deren Name nicht übereinstimmt, + werden beim erneuten Scannen ignoriert. + +.. note:: + + Das Vorschau-Thumbnail wird im Stammverzeichnis des Themes unter dem + festen Namen ``thumbnail.png`` abgelegt (es wird in der Theme-Liste + der Administrationsoberfläche angezeigt). Dieses Bild wird anhand + des Dateinamens erkannt, nicht über ein Feld im Manifest. Empfohlen + wird eine Größe von maximal 512 KB und maximal 512×512 Pixeln. + +Auslieferung und API +--------------------- + +- Statische Themes werden unter ``/themes//`` ausgeliefert + (```` ist der Wert von ``name`` in ``theme.yml``). +- Wenn ``spaFallback`` aktiviert ist, wird für die Pfade ``/``, + ``/search``, ``/help``, ``/error``, ``/profile``, ``/cache`` und + ``/chat`` jeweils das Einstiegs-HTML (Standard: ``index.html``) + zurückgegeben, und das weitere Routing übernimmt die SPA. +- Die Administrationsoberfläche (``/admin/*``), ``/api/*``, die + Anmeldeseite und Ähnliches fallen nicht unter das statische Theme und + werden vom |Fess|-Kern selbst verarbeitet. +- Die SPA des Themes ruft Daten wie Suchergebnisse und Chat über die + ``/api/v2/*`` API ab. + +Packaging +--------- + +Mit ``scripts/package.sh`` aus dem Repository +`fess-themes `__ können Sie +das Theme zu einem ZIP für die Verteilung zusammenfassen. -1. Benutzerdefiniertes Logo in ``images/logo.png`` platzieren -2. Logo in CSS referenzieren: +:: -.. code-block:: css + ./scripts/package.sh example - .logo img { - content: url("../images/logo.png"); - max-height: 40px; - } +Es wird ``dist/example-.zip`` erzeugt (```` ist der +Wert von ``version`` in ``theme.yml``). -Template-Anpassung ------------------- +.. note:: -Templates sind im JSP-Format. + ``theme.yml`` muss im Stammverzeichnis des ZIP abgelegt werden. Wird + die Datei in einem Unterverzeichnis abgelegt, wird sie beim + Hochladen nicht erkannt. -``templates/search.html`` (Auszug): +Installation und Aktivierung +------------------------------ -.. code-block:: html +1. Öffnen Sie in der Administrationsoberfläche „System" → „Theme" + (``/admin/theme/``). +2. Laden Sie die erstellte ZIP-Datei hoch. +3. Wählen Sie auf der Listenseite im Dropdown-Menü „Standard-Theme" das + gewünschte Theme aus, und klicken Sie auf die Schaltfläche + „Festlegen", um es zu aktivieren. -
-

Benutzerdefiniertes Suchportal

-

Interne Dokumente durchsuchen

-
+Der Aktivierungsmechanismus funktioniert wie folgt. -Theme-Registrierung -=================== +- Beim Klicken auf die Schaltfläche „Festlegen" wird der Name des + ausgewählten Themes in der Systemeigenschaft ``theme.default`` + gespeichert und wird so zum systemweiten Standard-Theme. +- Wenn der Theme-Name mit dem Schlüssel eines virtuellen Hosts + übereinstimmt, wird das Theme nur beim Zugriff auf diesen virtuellen + Host angewendet. Dadurch kann das Theme pro virtuellem Host + umgeschaltet werden. +- Wenn Sie das Verzeichnis ``themes/`` direkt auf der Festplatte + aktualisieren, können Sie mit „Neu laden" ein erneutes Scannen + auslösen. -pom.xml -------- +.. note:: -.. code-block:: xml + Für das Hochladen von ZIP-Dateien gelten Obergrenzen für + Dateigröße, Gesamtgröße nach dem Entpacken und Anzahl der Einträge; + diese lassen sich über die ``theme.*``-Eigenschaften in + ``fess_config.properties`` anpassen (Beispiel: + ``theme.upload.max.size`` beträgt standardmäßig 50MB, + ``theme.directory.path`` ist standardmäßig ``themes``). Beim + Entpacken werden Prüfungen durchgeführt, um Angriffe durch ZIP Slip + und Zip Bombs zu verhindern. - org.codelibs.fess - fess-theme-example - 15.8.0 - jar +JAR-Theme-Plugin (Legacy) +============================ -Konfigurationsdatei -------------------- +Ein JAR-Theme-Plugin ist ein Plugin, das die Verzeichnisse ``view`` / +``css`` / ``js`` / ``images`` des |Fess|-Kerns pro Theme-Name +überschreibt. Zur allgemeinen Struktur und Build-Methode von Plugins +siehe auch :doc:`plugin-architecture`. -``src/main/resources/theme.properties``: +Struktur +-------- :: - theme.name=example - theme.display.name=Example Theme - theme.version=1.0.0 + fess-theme-example/ + ├── pom.xml + └── src/main/resources/ + ├── view/ # JSP-Dateien (search.jsp, index.jsp, header.jsp usw.) + ├── css/ # CSS-Dateien (style.css usw.) + ├── js/ # JavaScript-Dateien + └── images/ # Bilddateien (logo.png usw.) + +.. note:: + + Views (Templates) liegen im JSP-Format vor. Als oberste + Ressourcenverzeichnisse werden nur die vier Verzeichnisse ``view`` / + ``css`` / ``js`` / ``images`` erkannt. Der Artefaktname muss mit + ``fess-theme-`` beginnen. + +pom.xml +------- -Installation -============ +Das Plugin wird als jar mit ``fess-parent`` als übergeordnetem POM +gebaut. Da ein Theme ausschließlich aus Ressourcen besteht, müssen in +der Regel keine zusätzlichen Abhängigkeiten deklariert werden. + +.. code-block:: xml + + + + 4.0.0 + + fess-theme-example + 15.8.0 + jar + + + org.codelibs.fess + fess-parent + 15.8.0 + + + + +Anpassung von CSS und Bildern +-------------------------------- + +Die Suchoberfläche besteht aus JSPs auf Bootstrap-Basis. Sie können CSS +überschreiben, um Farbschema und Layout zu ändern, oder +``images/logo.png`` ersetzen, um das Logo zu ändern. Welche +Klassennamen und welches Markup betroffen sind, entnehmen Sie den +tatsächlichen JSPs (``view/index.jsp`` / ``view/search.jsp`` usw.). + +Build und Installation +------------------------ :: - ./bin/fess-plugin install fess-theme-example + mvn clean package + +Im Verzeichnis ``target/`` wird eine JAR-Datei erzeugt (Beispiel: +``fess-theme-example-15.8.0.jar``). Sie kann über die +Administrationsoberfläche unter „System" → „Plugin" installiert +werden. Details zum Installationsvorgang finden Sie unter +:doc:`../admin/plugin-guide`. + +Nach der Installation werden die einzelnen Verzeichnisse im JAR pro +Theme-Name an folgende Orte entpackt (der Theme-Name ist der Teil des +Artefaktnamens ohne das Präfix ``fess-theme-``; im obigen Beispiel +``example``). + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Verzeichnis im JAR + - Zielort + * - ``view/`` + - ``WEB-INF/view//`` + * - ``css/`` + - ``css//`` + * - ``js/`` + - ``js//`` + * - ``images/`` + - ``images//`` + +Aktivierung +----------- + +JAR-Themes werden über die Funktion für virtuelle Hosts aktiviert. +Wenn Sie den Schlüssel eines virtuellen Hosts mit dem Theme-Namen +abgleichen, wird das Theme beim Zugriff auf diesen Host angewendet. -Theme in der Administrationsoberflache auswahlen: +1. Ordnen Sie in den Einstellungen für virtuelle Hosts unter „System" + → „Allgemein" den ``Host``-Header der Anfrage dem Theme-Namen + (Schlüssel des virtuellen Hosts) zu, zum Beispiel + ``Host:localhost:8080=example``. +2. Legen Sie bei Bedarf denselben Namen (``example``) auch für + virtuelle Hosts an anderen Stellen fest, etwa in den + Web-Crawling-Einstellungen. -1. "System" -> "Design" -2. Theme auswahlen -3. Speichern und anwenden +Details zur Konfiguration virtueller Hosts finden Sie unter +:doc:`../admin/general-guide`. -Beispiel-Themes -=============== +Beispiele für vorhandene Themes +=================================== +- `fess-themes `__ - Sammlung + statischer Themes (enthält mehrere statische Themes wie + ``codesearch`` und ``docsearch``) - `fess-theme-simple `__ -- `fess-theme-minimal `__ + - JAR-Theme +- `fess-theme-classic `__ + - JAR-Theme Referenzinformationen -===================== +========================= - :doc:`plugin-architecture` - Plugin-Architektur -- :doc:`../admin/design-guide` - Design-Einstellungsanleitung +- :doc:`../admin/design-guide` - Seitengestaltung (direkte Bearbeitung + von JSP, CSS und Bildern) +- :doc:`../admin/plugin-guide` - Plugin-Installation diff --git a/en/15.8/dev/theme-development.rst b/en/15.8/dev/theme-development.rst index 274d3307..f14b4af5 100644 --- a/en/15.8/dev/theme-development.rst +++ b/en/15.8/dev/theme-development.rst @@ -5,128 +5,323 @@ Theme Development Guide Overview ======== -Using the |Fess| theme system, you can customize the design of the search screen. -Themes can be distributed as plugins, and you can switch between multiple themes. +In |Fess|, you can customize the design of the search screen using the +following two methods. -Theme Structure -=============== +Static Theme + A mechanism introduced in |Fess| 15.7. Themes are distributed as + ZIP files, uploaded through the admin console, and enabled there. + The theme itself is an independent SPA (Single Page Application) + that uses the ``/api/v2/*`` API and does not depend on the |Fess| + core's JSP. This approach is recommended when creating a new theme. + +JAR Theme Plugin (Legacy) + A traditional plugin that overrides ``view`` / ``css`` / ``js`` / + ``images``. It is built as a JAR and installed as a plugin. Use + this when you want to partially replace existing JSP-based screens. + +.. note:: + + Static themes are available in |Fess| 15.7 and later. If you are + targeting 15.6 or earlier, use a JAR theme plugin instead. For how + to directly edit the search screen's JSP, CSS, and images from the + admin console, see :doc:`../admin/design-guide`. + +Static Theme +============ + +A static theme is a collection of static resources that includes a +``theme.yml`` manifest and ``index.html``. Implement the theme itself +as a front-end application that calls the |Fess| ``/api/v2/*`` API. + +Structure +--------- + +A static theme has the following directory structure. :: - fess-theme-example/ - ├── pom.xml - └── src/main/resources/ - └── theme/example/ - ├── css/ - │ ├── style.css - │ └── custom.css - ├── js/ - │ └── custom.js - ├── images/ - │ └── logo.png - └── templates/ - └── search.html + example/ + ├── theme.yml # Manifest (required) + ├── index.html # SPA entry HTML + ├── assets/ # Static resources such as JavaScript and CSS + │ └── styles.css + ├── i18n/ # Localized messages (messages..json) + │ └── messages.en.json + ├── help/ # Help definitions (.json) + │ └── en.json + └── thumbnail.png # Preview image (optional) + +Manifest (theme.yml) +-------------------- + +``theme.yml`` is a required manifest placed at the root of the ZIP +file. The following is an example of a minimal configuration. + +.. code-block:: yaml + + apiVersion: fess.codelibs.org/v1 + kind: StaticTheme + name: example + displayName: "Example Theme" + version: "1.0.0" + minFessVersion: "15.7" + entry: index.html + spaFallback: true + +The fields that can be specified are as follows. + +.. list-table:: + :header-rows: 1 + :widths: 22 12 66 + + * - Field + - Required + - Description + * - ``apiVersion`` + - Required + - Fixed value ``fess.codelibs.org/v1``. + * - ``kind`` + - Required + - Fixed value ``StaticTheme``. + * - ``name`` + - Required + - The theme name. Must match ``^[a-z0-9][a-z0-9_-]{0,63}$``. It is + used for the directory name the theme is expanded into under + ``themes/`` (when uploading, this is determined automatically + from ``name``), and for the delivery URL (``/themes//``). + * - ``displayName`` + - Required + - The name displayed in the admin console. + * - ``version`` + - Required + - Semantic versioning format (e.g., ``1.0.0``, ``1.2.3-beta.1``). + * - ``author`` + - Optional + - The author's name. + * - ``description`` + - Optional + - A description of the theme. + * - ``license`` + - Optional + - The license. + * - ``homepage`` + - Optional + - The homepage URL. + * - ``minFessVersion`` + - Optional + - The minimum |Fess| version the theme supports. + * - ``supportedLocales`` + - Optional + - A list of supported locales (e.g., ``[en, ja, de]``). + * - ``entry`` + - Optional + - The SPA entry HTML. Defaults to ``index.html``. + * - ``spaFallback`` + - Optional + - Whether the SPA fallback is enabled. Defaults to ``true``. + +.. note:: + + When uploading via ZIP, the destination directory name is + determined automatically from ``name``. If you place a theme + manually in the ``themes/`` directory, make sure the directory name + matches ``name``. Themes whose directory name does not match are + ignored on rescan. + +.. note:: + + The preview thumbnail is placed at the root of the theme with the + fixed name ``thumbnail.png`` (it is displayed in the theme list in + the admin console). This image is recognized by its file name, not + by a manifest field. A size of 512KB or less and 512x512 pixels or + less is recommended. + +Serving and API +--------------- + +- A static theme is served under ``/themes//`` (```` is + the ``name`` in ``theme.yml``). +- When ``spaFallback`` is enabled, the entry HTML (``index.html`` by + default) is returned for the paths ``/``, ``/search``, ``/help``, + ``/error``, ``/profile``, ``/cache``, and ``/chat``, and subsequent + routing is handled by the SPA. +- The admin console (``/admin/*``), ``/api/*``, the login screen, and + similar are not covered by the static theme and are handled by the + |Fess| core. +- The theme's SPA retrieves data such as search results and chat from + the ``/api/v2/*`` API. + +Packaging +--------- + +Using ``scripts/package.sh`` from the +`fess-themes `__ repository, +you can package a theme into a ZIP for distribution. -Basic Theme Creation -==================== +:: -CSS Customization ------------------ + ./scripts/package.sh example -``css/style.css``: +``dist/example-.zip`` is generated (```` is the +``version`` in ``theme.yml``). -.. code-block:: css +.. note:: - /* Header customization */ - .navbar { - background-color: #1a237e; - } + ``theme.yml`` must be placed at the root of the ZIP. If it is + placed in a subdirectory, it will not be recognized when uploaded. - /* Search box style */ - .search-box { - border-radius: 25px; - box-shadow: 0 2px 5px rgba(0,0,0,0.2); - } +Installation and Activation +---------------------------- - /* Search result style */ - .search-result-item { - border-left: 3px solid #1a237e; - padding-left: 15px; - } +1. In the admin console, open "System" -> "Theme" (``/admin/theme/``). +2. Upload the ZIP file you created. +3. On the list page, select the target theme from the "Default Theme" + drop-down and click the "Set" button to enable it. -Logo Change ------------ +The activation mechanism works as follows. -1. Place custom logo at ``images/logo.png`` -2. Reference logo in CSS: +- Clicking "Set" saves the selected theme name to the + ``theme.default`` system property, making it the system-wide default + theme. +- If you match the theme name to a virtual host key, the theme is + applied only when that virtual host is accessed. This lets you + switch themes per virtual host. +- If you update the ``themes/`` directory on disk directly, you can + rescan it with "Reload". -.. code-block:: css +.. note:: - .logo img { - content: url("../images/logo.png"); - max-height: 40px; - } + There are limits on ZIP uploads, such as file size, total size + after extraction, and number of entries, which can be adjusted with + the ``theme.*`` properties in ``fess_config.properties`` (for + example, ``theme.upload.max.size`` defaults to 50MB, and + ``theme.directory.path`` defaults to ``themes``). During extraction, + validation is performed to prevent ZIP Slip and zip bomb attacks. -Template Customization ----------------------- +JAR Theme Plugin (Legacy) +========================= -Templates are in JSP format. +A JAR theme plugin overrides the |Fess| core's ``view`` / ``css`` / +``js`` / ``images`` directories on a per-theme-name basis. For the +general plugin structure and build process, also see +:doc:`plugin-architecture`. -``templates/search.html`` (excerpt): +Structure +--------- -.. code-block:: html +:: -
-

Custom Search Portal

-

Search internal documents

-
+ fess-theme-example/ + ├── pom.xml + └── src/main/resources/ + ├── view/ # JSP files (search.jsp, index.jsp, header.jsp, etc.) + ├── css/ # CSS files (style.css, etc.) + ├── js/ # JavaScript files + └── images/ # Image files (logo.png, etc.) -Theme Registration -================== +.. note:: + + Views (templates) are in JSP format. Only the four top-level + resource directories ``view`` / ``css`` / ``js`` / ``images`` are + recognized. The artifact name must start with ``fess-theme-``. pom.xml ------- +The plugin is built as a jar with ``fess-parent`` as the parent POM. +Since a theme consists only of resources, there is usually no need to +declare additional dependencies. + .. code-block:: xml - org.codelibs.fess - fess-theme-example - 15.8.0 - jar + + + 4.0.0 -Configuration File ------------------- + fess-theme-example + 15.8.0 + jar -``src/main/resources/theme.properties``: + + org.codelibs.fess + fess-parent + 15.8.0 + + + -:: +Customizing CSS and Images +--------------------------- - theme.name=example - theme.display.name=Example Theme - theme.version=1.0.0 +The search screen is built with Bootstrap-based JSPs. You can override +the CSS to change colors and layout, or replace ``images/logo.png`` to +change the logo. For the target class names and markup, check the +actual JSPs (``view/index.jsp``, ``view/search.jsp``, etc.). -Installation -============ +Build and Installation +----------------------- :: - ./bin/fess-plugin install fess-theme-example - -Select theme from admin console: - -1. Go to "System" -> "Design" -2. Select theme -3. Save and apply - -Existing Theme Examples -======================= - -- `fess-theme-simple `__ -- `fess-theme-minimal `__ + mvn clean package + +A JAR file (e.g., ``fess-theme-example-15.8.0.jar``) is generated in +the ``target/`` directory. You can install it from "System" -> +"Plugin" in the admin console. For details on the installation +procedure, see :doc:`../admin/plugin-guide`. + +Once installed, each directory in the JAR is expanded to the following +locations, per theme name (the theme name is the artifact name with +the ``fess-theme-`` prefix removed; in the example above, ``example``). + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Directory in the JAR + - Expansion destination + * - ``view/`` + - ``WEB-INF/view//`` + * - ``css/`` + - ``css//`` + * - ``js/`` + - ``js//`` + * - ``images/`` + - ``images//`` + +Activation +---------- + +A JAR theme is activated using the virtual host feature. If you match +a virtual host key to the theme name, the theme is applied when that +host is accessed. + +1. In the virtual host settings under "System" -> "General", map the + request's ``Host`` header to a theme name (virtual host key), for + example ``Host:localhost:8080=example``. +2. If needed, also set the same name (``example``) for the virtual + host in the crawling web configuration, etc. + +For details on how to configure virtual hosts, see +:doc:`../admin/general-guide`. + +Examples of Existing Themes +============================ + +- `fess-themes `__ - A + collection of static themes (includes multiple static themes such as + ``codesearch`` and ``docsearch``) +- `fess-theme-simple `__ - JAR theme +- `fess-theme-classic `__ - JAR theme Reference ========= -- :doc:`plugin-architecture` - Plugin Architecture -- :doc:`../admin/design-guide` - Design Settings Guide - +- :doc:`plugin-architecture` - Plugin architecture +- :doc:`../admin/design-guide` - Page Design (direct editing of JSP, + CSS, and images) +- :doc:`../admin/plugin-guide` - Plugin installation diff --git a/es/15.8/dev/theme-development.rst b/es/15.8/dev/theme-development.rst index f6abbc7b..c08d0406 100644 --- a/es/15.8/dev/theme-development.rst +++ b/es/15.8/dev/theme-development.rst @@ -1,131 +1,348 @@ -================================== -Guia de Desarrollo de Temas -================================== +=========================== +Guía de Desarrollo de Temas +=========================== -Vision General +Visión General ============== -Usando el sistema de temas de |Fess|, puede personalizar el diseno de la pantalla de busqueda. -Los temas se pueden distribuir como plugins y puede alternar entre multiples temas. +En |Fess|, el diseño de la pantalla de búsqueda se puede personalizar +mediante los dos métodos siguientes. -Estructura del Tema -=================== +Tema Estático (Static Theme) + Es el mecanismo introducido en |Fess| 15.7. El tema se distribuye + como un archivo ZIP, que se sube y se activa desde la consola de + administración. El propio tema es una SPA (Single Page Application, + aplicación de página única) independiente que utiliza la API + ``/api/v2/*`` y no depende de las JSP del propio |Fess|. Se + recomienda este método para crear temas nuevos. -:: +Plugin de Tema JAR (heredado) + Es el plugin de tipo tradicional que sobrescribe ``view`` / ``css`` + / ``js`` / ``images``. Se construye como JAR y se instala como + plugin. Se utiliza cuando se desea sustituir parcialmente las + pantallas basadas en JSP existentes. - fess-theme-example/ - ├── pom.xml - └── src/main/resources/ - └── theme/example/ - ├── css/ - │ ├── style.css - │ └── custom.css - ├── js/ - │ └── custom.js - ├── images/ - │ └── logo.png - └── templates/ - └── search.html - -Creacion Basica de Temas -======================== - -Personalizacion de CSS ----------------------- +.. note:: -``css/style.css``: + Los temas estáticos están disponibles a partir de |Fess| 15.7. Si el + objetivo son las versiones 15.6 o anteriores, utilice el plugin de + tema JAR. Para el método de edición directa de las JSP, el CSS y las + imágenes de la pantalla de búsqueda desde la consola de + administración, consulte :doc:`../admin/design-guide`. -.. code-block:: css +Tema Estático +============= - /* Personalizacion del encabezado */ - .navbar { - background-color: #1a237e; - } +Un tema estático es un conjunto de recursos estáticos que incluye el +manifiesto ``theme.yml`` y el archivo ``index.html``. El propio tema se +implementa como una aplicación frontend que invoca la API +``/api/v2/*`` de |Fess|. - /* Estilo del cuadro de busqueda */ - .search-box { - border-radius: 25px; - box-shadow: 0 2px 5px rgba(0,0,0,0.2); - } +Estructura +---------- - /* Estilo de los resultados de busqueda */ - .search-result-item { - border-left: 3px solid #1a237e; - padding-left: 15px; - } +Un tema estático tiene la siguiente estructura de directorios. -Cambio de Logo --------------- +:: -1. Coloque el logo personalizado en ``images/logo.png`` -2. Haga referencia al logo en el CSS: + example/ + ├── theme.yml # Manifiesto (obligatorio) + ├── index.html # HTML de entrada de la SPA + ├── assets/ # Recursos estáticos como JavaScript y CSS + │ └── styles.css + ├── i18n/ # Mensajes multilingües (messages..json) + │ └── messages.en.json + ├── help/ # Definiciones de ayuda (.json) + │ └── en.json + └── thumbnail.png # Imagen de vista previa (opcional) + +Manifiesto (theme.yml) +---------------------- -.. code-block:: css +``theme.yml`` es el manifiesto obligatorio que debe colocarse en la raíz +del ZIP. A continuación se muestra un ejemplo de configuración mínima. + +.. code-block:: yaml + + apiVersion: fess.codelibs.org/v1 + kind: StaticTheme + name: example + displayName: "Example Theme" + version: "1.0.0" + minFessVersion: "15.7" + entry: index.html + spaFallback: true + +Los campos que se pueden especificar son los siguientes. + +.. list-table:: + :header-rows: 1 + :widths: 22 12 66 + + * - Campo + - Obligatorio + - Descripción + * - ``apiVersion`` + - Obligatorio + - Valor fijo ``fess.codelibs.org/v1``. + * - ``kind`` + - Obligatorio + - Valor fijo ``StaticTheme``. + * - ``name`` + - Obligatorio + - Nombre del tema. Debe coincidir con + ``^[a-z0-9][a-z0-9_-]{0,63}$``. Se utiliza como nombre del + directorio del tema que se expande bajo ``themes/`` (al subir el + archivo, este se determina automáticamente a partir de + ``name``) y como URL de distribución (``/themes//``). + * - ``displayName`` + - Obligatorio + - Nombre que se muestra en la consola de administración. + * - ``version`` + - Obligatorio + - Formato de versionado semántico (ejemplo: ``1.0.0``, + ``1.2.3-beta.1``). + * - ``author`` + - Opcional + - Nombre del autor. + * - ``description`` + - Opcional + - Descripción del tema. + * - ``license`` + - Opcional + - Licencia. + * - ``homepage`` + - Opcional + - URL de la página de inicio. + * - ``minFessVersion`` + - Opcional + - Versión mínima de |Fess| compatible con el tema. + * - ``supportedLocales`` + - Opcional + - Lista de configuraciones regionales admitidas (ejemplo: + ``[en, ja, de]``). + * - ``entry`` + - Opcional + - HTML de entrada de la SPA. El valor predeterminado es + ``index.html``. + * - ``spaFallback`` + - Opcional + - Habilita o deshabilita el fallback de la SPA. El valor + predeterminado es ``true``. + +.. note:: + + Al subir el archivo desde un ZIP, el nombre del directorio de + destino de la expansión se determina automáticamente a partir de + ``name``. Si coloca el tema manualmente en el directorio + ``themes/``, haga que el nombre del directorio coincida con + ``name``. Los temas que no coincidan se ignorarán al volver a + escanear. + +.. note:: + + La miniatura de vista previa se coloca en la raíz del tema con el + nombre fijo ``thumbnail.png`` (se muestra en la lista de temas de la + consola de administración). Esta imagen no se reconoce mediante un + campo del manifiesto, sino por el nombre del archivo. Se recomienda + que el tamaño no supere 512 KB y que las dimensiones no superen + 512×512 píxeles. + +Distribución y API +------------------ + +- Los temas estáticos se distribuyen bajo ``/themes//`` (donde + ```` es el ``name`` de ``theme.yml``). +- Cuando ``spaFallback`` está habilitado, se devuelve el HTML de + entrada (por defecto ``index.html``) en cada una de las rutas ``/``, + ``/search``, ``/help``, ``/error``, ``/profile``, ``/cache`` y + ``/chat``, y el enrutamiento posterior lo gestiona la SPA. +- La consola de administración (``/admin/*``), ``/api/*``, la pantalla + de inicio de sesión, etc., quedan fuera del alcance de los temas + estáticos y son gestionados por el propio |Fess|. +- La SPA del tema obtiene datos como los resultados de búsqueda y el + chat a través de la API ``/api/v2/*``. + +Empaquetado +----------- + +Si utiliza ``scripts/package.sh`` del repositorio `fess-themes +`__, puede empaquetar el tema +en un ZIP para su distribución. - .logo img { - content: url("../images/logo.png"); - max-height: 40px; - } +:: -Personalizacion de Plantillas ------------------------------ + ./scripts/package.sh example -Las plantillas estan en formato JSP. +Se genera ``dist/example-.zip`` (donde ```` es el +``version`` de ``theme.yml``). -``templates/search.html`` (parcial): +.. note:: -.. code-block:: html + ``theme.yml`` debe colocarse en la raíz del ZIP. Si se coloca en un + subdirectorio, no se reconocerá al subirlo. -
-

Portal de Busqueda Personalizado

-

Buscar documentos internos

-
+Instalación y Activación +------------------------ -Registro del Tema -================= +1. Abra «Sistema» → «Tema» (``/admin/theme/``) en la consola de + administración. +2. Suba el archivo ZIP creado. +3. En la página de la lista, seleccione el tema deseado en el menú + desplegable «Tema predeterminado» y pulse el botón «Establecer» para + activarlo. + +El mecanismo de activación es el siguiente. + +- Al pulsar el botón «Establecer», el nombre del tema seleccionado se + guarda en la propiedad del sistema ``theme.default`` y se convierte + en el tema predeterminado de todo el sistema. +- Si el nombre del tema coincide con la clave de un host virtual, el + tema solo se aplica al acceder a ese host virtual. Esto permite + cambiar de tema según el host virtual. +- Si actualiza directamente el directorio ``themes/`` en el disco, + puede volver a escanearlo con «Recargar». + +.. note:: + + La subida del ZIP tiene límites como el tamaño del archivo, el + tamaño total tras la expansión y el número de entradas, que se + pueden ajustar mediante las propiedades ``theme.*`` de + ``fess_config.properties`` (por ejemplo, ``theme.upload.max.size`` + tiene un valor predeterminado de 50MB y ``theme.directory.path`` + tiene un valor predeterminado de ``themes``). Durante la expansión + se realizan comprobaciones para prevenir ataques de tipo ZIP Slip y + zip bomb. + +Plugin de Tema JAR (heredado) +============================= + +El plugin de tema JAR es un plugin que sobrescribe los directorios +``view`` / ``css`` / ``js`` / ``images`` del propio |Fess| para cada +nombre de tema. Para conocer la estructura general de los plugins y el +método de compilación, consulte también :doc:`plugin-architecture`. + +Estructura +---------- -pom.xml -------- +:: -.. code-block:: xml + fess-theme-example/ + ├── pom.xml + └── src/main/resources/ + ├── view/ # Archivos JSP (search.jsp, index.jsp, header.jsp, etc.) + ├── css/ # Archivos CSS (style.css, etc.) + ├── js/ # Archivos JavaScript + └── images/ # Archivos de imagen (logo.png, etc.) - org.codelibs.fess - fess-theme-example - 15.8.0 - jar +.. note:: -Archivo de Configuracion ------------------------- + Las vistas (plantillas) están en formato JSP. Solo se reconocen los + cuatro directorios de nivel superior de recursos: ``view`` / ``css`` + / ``js`` / ``images``. El nombre del artefacto debe comenzar con + ``fess-theme-``. -``src/main/resources/theme.properties``: +pom.xml +------- -:: +El plugin se construye como un jar con ``fess-parent`` como POM padre. +Puesto que el tema se compone únicamente de recursos, normalmente no es +necesario declarar dependencias adicionales. - theme.name=example - theme.display.name=Example Theme - theme.version=1.0.0 +.. code-block:: xml -Instalacion -=========== + + + 4.0.0 + + fess-theme-example + 15.8.0 + jar + + + org.codelibs.fess + fess-parent + 15.8.0 + + + + +Personalización de CSS e Imágenes +---------------------------------- + +La pantalla de búsqueda está compuesta por JSP basadas en Bootstrap. +Puede sobrescribir el CSS para cambiar los colores y el diseño, o +sustituir ``images/logo.png`` para cambiar el logotipo. Para conocer +los nombres de clase y el marcado correspondientes, consulte las JSP +reales (``view/index.jsp``, ``view/search.jsp``, etc.). + +Compilación e Instalación +-------------------------- :: - ./bin/fess-plugin install fess-theme-example - -Seleccione el tema desde la pantalla de administracion: - -1. "Sistema" -> "Diseno" -2. Seleccione el tema -3. Guarde y aplique + mvn clean package + +En el directorio ``target/`` se genera un archivo JAR (por ejemplo, +``fess-theme-example-15.8.0.jar``). Puede instalarlo desde «Sistema» → +«Plugin» en la consola de administración. Para más detalles sobre el +procedimiento de instalación, consulte :doc:`../admin/plugin-guide`. + +Al instalarlo, cada directorio dentro del JAR se expande, para cada +nombre de tema, en las siguientes ubicaciones (el nombre del tema es +la parte del nombre del artefacto que resulta de eliminar +``fess-theme-``; en el ejemplo anterior, ``example``). + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Directorio dentro del JAR + - Destino de expansión + * - ``view/`` + - ``WEB-INF/view//`` + * - ``css/`` + - ``css//`` + * - ``js/`` + - ``js//`` + * - ``images/`` + - ``images//`` + +Activación +---------- + +Los temas JAR se activan mediante la función de host virtual. Si la +clave del host virtual coincide con el nombre del tema, este se aplica +al acceder a ese host. + +1. En la configuración de host virtual de «Sistema» → «General», + asocie la cabecera ``Host`` de la solicitud con el nombre del tema + (la clave del host virtual), como en + ``Host:localhost:8080=example``. +2. Si es necesario, configure el mismo nombre (``example``) también en + el host virtual de la configuración web del rastreo, entre otros. + +Para más detalles sobre cómo configurar el host virtual, consulte +:doc:`../admin/general-guide`. Ejemplos de Temas Existentes ============================ +- `fess-themes `__ - + Colección de temas estáticos (incluye varios temas estáticos como + ``codesearch`` y ``docsearch``) - `fess-theme-simple `__ -- `fess-theme-minimal `__ + - Tema JAR +- `fess-theme-classic `__ + - Tema JAR -Informacion de Referencia +Información de Referencia ========================= - :doc:`plugin-architecture` - Arquitectura de plugins -- :doc:`../admin/design-guide` - Guia de configuracion de diseno +- :doc:`../admin/design-guide` - Diseño de página (edición directa de + JSP, CSS e imágenes) +- :doc:`../admin/plugin-guide` - Instalación de plugins diff --git a/fr/15.8/dev/theme-development.rst b/fr/15.8/dev/theme-development.rst index a48b096b..21f822b3 100644 --- a/fr/15.8/dev/theme-development.rst +++ b/fr/15.8/dev/theme-development.rst @@ -1,131 +1,337 @@ ================================== -Guide de developpement de themes +Guide de développement des thèmes ================================== -Vue d'ensemble -============== - -Le systeme de themes de |Fess| permet de personnaliser le design de l'ecran de recherche. -Les themes peuvent etre distribues sous forme de plugins et vous pouvez basculer entre plusieurs themes. +Aperçu +====== -Structure d'un theme -==================== +Avec |Fess|, vous pouvez personnaliser le design de l'écran de recherche de deux façons : -:: +Thème statique (Static Theme) + Mécanisme introduit dans |Fess| 15.7. Le thème est distribué sous forme de + fichier ZIP, téléversé puis activé depuis l'écran d'administration. Le + thème lui-même est une SPA (Single Page Application, application + monopage) indépendante qui utilise l'API ``/api/v2/*`` et ne dépend pas + des JSP du cœur de |Fess|. Cette méthode est recommandée pour créer un + nouveau thème. - fess-theme-example/ - ├── pom.xml - └── src/main/resources/ - └── theme/example/ - ├── css/ - │ ├── style.css - │ └── custom.css - ├── js/ - │ └── custom.js - ├── images/ - │ └── logo.png - └── templates/ - └── search.html +Plugin de thème JAR (legacy) + Plugin de type traditionnel qui remplace les répertoires ``view`` / + ``css`` / ``js`` / ``images``. Il est construit sous forme de JAR et + installé comme un plugin. Utilisez-le lorsque vous souhaitez remplacer + partiellement les écrans existants basés sur JSP. -Creation d'un theme de base -=========================== +.. note:: -Personnalisation CSS --------------------- + Les thèmes statiques sont disponibles à partir de |Fess| 15.7. Pour cibler + les versions 15.6 et antérieures, utilisez un plugin de thème JAR. Pour + modifier directement les JSP, CSS et images de l'écran de recherche depuis + l'écran d'administration, reportez-vous à :doc:`../admin/design-guide`. -``css/style.css``: +Thème statique +============== -.. code-block:: css +Un thème statique est un ensemble de ressources statiques comprenant le +manifeste ``theme.yml`` et ``index.html``. Le thème lui-même est implémenté +comme une application front-end qui appelle l'API ``/api/v2/*`` de |Fess|. - /* Personnalisation de l'en-tete */ - .navbar { - background-color: #1a237e; - } +Structure +--------- - /* Style de la zone de recherche */ - .search-box { - border-radius: 25px; - box-shadow: 0 2px 5px rgba(0,0,0,0.2); - } +Un thème statique adopte la structure de répertoires suivante. - /* Style des resultats de recherche */ - .search-result-item { - border-left: 3px solid #1a237e; - padding-left: 15px; - } +:: -Changement du logo ------------------- + example/ + ├── theme.yml # Manifeste (obligatoire) + ├── index.html # HTML d'entrée de la SPA + ├── assets/ # Ressources statiques telles que JavaScript, CSS + │ └── styles.css + ├── i18n/ # Messages multilingues (messages..json) + │ └── messages.en.json + ├── help/ # Définitions d'aide (.json) + │ └── en.json + └── thumbnail.png # Image d'aperçu (facultatif) + +Manifeste (theme.yml) +---------------------- + +``theme.yml`` est le manifeste obligatoire à placer à la racine du ZIP. Voici +un exemple de configuration minimale. + +.. code-block:: yaml + + apiVersion: fess.codelibs.org/v1 + kind: StaticTheme + name: example + displayName: "Example Theme" + version: "1.0.0" + minFessVersion: "15.7" + entry: index.html + spaFallback: true + +Les champs pouvant être spécifiés sont les suivants. + +.. list-table:: + :header-rows: 1 + :widths: 22 12 66 + + * - Champ + - Obligatoire + - Description + * - ``apiVersion`` + - Obligatoire + - Valeur fixe ``fess.codelibs.org/v1``. + * - ``kind`` + - Obligatoire + - Valeur fixe ``StaticTheme``. + * - ``name`` + - Obligatoire + - Nom du thème. Doit correspondre à ``^[a-z0-9][a-z0-9_-]{0,63}$``. Il + est utilisé comme nom du répertoire du thème déployé sous ``themes/`` + (déterminé automatiquement à partir de ce ``name`` lors du + téléversement), ainsi que pour l'URL de diffusion (``/themes//``). + * - ``displayName`` + - Obligatoire + - Nom affiché dans l'écran d'administration. + * - ``version`` + - Obligatoire + - Format de gestion sémantique des versions (exemple : ``1.0.0``, + ``1.2.3-beta.1``). + * - ``author`` + - Facultatif + - Nom de l'auteur. + * - ``description`` + - Facultatif + - Description du thème. + * - ``license`` + - Facultatif + - Licence. + * - ``homepage`` + - Facultatif + - URL de la page d'accueil. + * - ``minFessVersion`` + - Facultatif + - Version minimale de |Fess| prise en charge par le thème. + * - ``supportedLocales`` + - Facultatif + - Liste des locales prises en charge (exemple : ``[en, ja, de]``). + * - ``entry`` + - Facultatif + - HTML d'entrée de la SPA. Valeur par défaut : ``index.html``. + * - ``spaFallback`` + - Facultatif + - Active ou désactive le fallback SPA. Valeur par défaut : ``true``. + +.. note:: + + Lors d'un téléversement depuis un ZIP, le nom du répertoire de destination + est déterminé automatiquement à partir de ``name``. Si vous placez + manuellement un thème dans le répertoire ``themes/``, veillez à faire + correspondre le nom du répertoire avec ``name``. Les thèmes dont le nom ne + correspond pas sont ignorés lors de la nouvelle analyse. + +.. note:: + + La miniature d'aperçu doit être placée à la racine du thème sous le nom + fixe ``thumbnail.png`` (elle est affichée dans la liste des thèmes de + l'écran d'administration). Cette image n'est pas un champ du manifeste ; + elle est reconnue par son nom de fichier. Une taille inférieure à 512 Ko + et à 512 × 512 pixels est recommandée. + +Diffusion et API +----------------- + +- Un thème statique est diffusé sous ``/themes//`` (```` + correspond au ``name`` défini dans ``theme.yml``). +- Lorsque ``spaFallback`` est activé, le HTML d'entrée (par défaut + ``index.html``) est renvoyé pour chacun des chemins ``/``, ``/search``, + ``/help``, ``/error``, ``/profile``, ``/cache`` et ``/chat``, et le routage + ultérieur est assuré par la SPA. +- L'écran d'administration (``/admin/*``), ``/api/*``, l'écran de connexion, + etc. ne sont pas concernés par le thème statique et sont traités par le + cœur de |Fess|. +- La SPA du thème récupère les données telles que les résultats de recherche + ou le chat depuis l'API ``/api/v2/*``. + +Empaquetage +----------- + +Le script ``scripts/package.sh`` du dépôt `fess-themes +`__ permet d'empaqueter le thème +dans un fichier ZIP destiné à la distribution. -1. Placer le logo personnalise dans ``images/logo.png`` -2. Referencer le logo dans le CSS: +:: -.. code-block:: css + ./scripts/package.sh example - .logo img { - content: url("../images/logo.png"); - max-height: 40px; - } +``dist/example-.zip`` est généré (```` correspond au +``version`` défini dans ``theme.yml``). -Personnalisation des templates ------------------------------- +.. note:: -Les templates sont au format JSP. + ``theme.yml`` doit être placé à la racine du ZIP. S'il se trouve dans un + sous-répertoire, il ne sera pas reconnu lors du téléversement. -``templates/search.html`` (extrait): +Installation et activation +--------------------------- -.. code-block:: html +1. Ouvrez « Système » → « Thème » (``/admin/theme/``) dans l'écran + d'administration. +2. Téléversez le fichier ZIP créé. +3. Sur la page de liste, sélectionnez le thème souhaité dans le menu + déroulant « Thème par défaut », puis cliquez sur le bouton « Définir » + pour l'activer. -
-

Portail de recherche personnalise

-

Rechercher dans les documents internes

-
+Le mécanisme d'activation est le suivant. -Enregistrement du theme -======================= +- Lorsque vous cliquez sur le bouton « Définir », le nom du thème sélectionné + est enregistré dans la propriété système ``theme.default`` et devient le + thème par défaut pour l'ensemble du système. +- Si le nom du thème correspond à la clé d'un hôte virtuel, le thème n'est + appliqué que lors de l'accès à cet hôte virtuel. Cela permet de changer de + thème pour chaque hôte virtuel. +- Si vous mettez à jour directement le répertoire ``themes/`` sur le disque, + vous pouvez relancer une analyse avec « Recharger ». -pom.xml -------- +.. note:: -.. code-block:: xml + Le téléversement du ZIP est soumis à des limites telles que la taille du + fichier, la taille totale après décompression et le nombre d'entrées ; ces + limites peuvent être ajustées via les propriétés ``theme.*`` de + ``fess_config.properties`` (par exemple, ``theme.upload.max.size`` vaut + 50 Mo par défaut et ``theme.directory.path`` vaut ``themes`` par défaut). + Lors de la décompression, des vérifications sont effectuées pour empêcher + les attaques de type ZIP Slip et zip bomb. - org.codelibs.fess - fess-theme-example - 15.8.0 - jar +Plugin de thème JAR (legacy) +============================ -Fichier de configuration ------------------------- +Un plugin de thème JAR est un plugin qui remplace les répertoires ``view`` / +``css`` / ``js`` / ``images`` du cœur de |Fess| pour chaque nom de thème. +Pour la structure générale des plugins et la méthode de build, reportez-vous +également à :doc:`plugin-architecture`. -``src/main/resources/theme.properties``: +Structure +--------- :: - theme.name=example - theme.display.name=Example Theme - theme.version=1.0.0 + fess-theme-example/ + ├── pom.xml + └── src/main/resources/ + ├── view/ # Fichiers JSP (search.jsp, index.jsp, header.jsp, etc.) + ├── css/ # Fichiers CSS (style.css, etc.) + ├── js/ # Fichiers JavaScript + └── images/ # Fichiers image (logo.png, etc.) -Installation -============ +.. note:: -:: + Les vues (templates) sont au format JSP. Seuls les quatre répertoires de + premier niveau ``view`` / ``css`` / ``js`` / ``images`` sont reconnus + comme ressources. Le nom de l'artefact doit commencer par + ``fess-theme-``. - ./bin/fess-plugin install fess-theme-example +pom.xml +------- -Selection du theme depuis l'interface d'administration: +Le plugin est construit comme un jar ayant ``fess-parent`` pour POM parent. +Comme le thème est constitué uniquement de ressources, il n'est généralement +pas nécessaire de déclarer de dépendances supplémentaires. -1. "Systeme" -> "Design" -2. Selectionner le theme -3. Sauvegarder et appliquer +.. code-block:: xml -Exemples de themes existants -============================ + + + 4.0.0 + + fess-theme-example + 15.8.0 + jar + + + org.codelibs.fess + fess-parent + 15.8.0 + + + + +Personnalisation du CSS et des images +--------------------------------------- + +L'écran de recherche est constitué de JSP basées sur Bootstrap. Vous pouvez +modifier les couleurs et la mise en page en remplaçant le CSS, ou changer le +logo en remplaçant ``images/logo.png``. Pour connaître les noms de classes et +le balisage concernés, consultez les JSP réelles (``view/index.jsp`` / +``view/search.jsp``, etc.). + +Build et installation +----------------------- -- `fess-theme-simple `__ -- `fess-theme-minimal `__ +:: -Informations complementaires -============================ + mvn clean package + +Le fichier JAR (par exemple ``fess-theme-example-15.8.0.jar``) est généré +dans le répertoire ``target/``. Vous pouvez l'installer depuis « Système » → +« Plugin » dans l'écran d'administration. Pour plus de détails sur la +procédure d'installation, reportez-vous à :doc:`../admin/plugin-guide`. + +Après l'installation, chaque répertoire du JAR est déployé pour le nom de +thème correspondant aux emplacements suivants (le nom du thème correspond à +la partie de l'artefact restant après avoir retiré ``fess-theme-`` ; dans +l'exemple ci-dessus, il s'agit de ``example``). + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Répertoire dans le JAR + - Emplacement de déploiement + * - ``view/`` + - ``WEB-INF/view//`` + * - ``css/`` + - ``css//`` + * - ``js/`` + - ``js//`` + * - ``images/`` + - ``images//`` + +Activation +---------- + +Un thème JAR s'active à l'aide de la fonctionnalité d'hôte virtuel. Si la clé +de l'hôte virtuel correspond au nom du thème, le thème est appliqué lors de +l'accès à cet hôte. + +1. Dans les paramètres d'hôte virtuel de « Système » → « Général », associez + l'en-tête ``Host`` de la requête au nom du thème (clé de l'hôte virtuel), + par exemple ``Host:localhost:8080=example``. +2. Si nécessaire, définissez également le même nom (``example``) pour + l'hôte virtuel des paramètres Web de crawl, entre autres. + +Pour plus de détails sur la configuration des hôtes virtuels, reportez-vous à +:doc:`../admin/general-guide`. + +Exemples de thèmes existants +============================= + +- `fess-themes `__ - Collection de + thèmes statiques (regroupe plusieurs thèmes statiques tels que + ``codesearch`` et ``docsearch``) +- `fess-theme-simple `__ - + Thème JAR +- `fess-theme-classic `__ - + Thème JAR + +Informations complémentaires +============================= - :doc:`plugin-architecture` - Architecture des plugins -- :doc:`../admin/design-guide` - Guide de configuration du design +- :doc:`../admin/design-guide` - Conception de la page (modification directe + des JSP, CSS et images) +- :doc:`../admin/plugin-guide` - Installation des plugins diff --git a/ja/15.8/dev/theme-development.rst b/ja/15.8/dev/theme-development.rst index 0c6ebf8b..88a4f435 100644 --- a/ja/15.8/dev/theme-development.rst +++ b/ja/15.8/dev/theme-development.rst @@ -5,127 +5,302 @@ 概要 ==== -|Fess| のテーマシステムを使用して、検索画面のデザインをカスタマイズできます。 -テーマはプラグインとして配布でき、複数のテーマを切り替えて使用できます。 +|Fess| では、検索画面のデザインを次の 2 つの方法でカスタマイズできます。 -テーマ構造 +静的テーマ (Static Theme) + |Fess| 15.7 で導入された仕組みです。テーマを ZIP ファイルとして配布し、 + 管理画面からアップロードして有効化します。テーマ本体は ``/api/v2/*`` API を + 利用する独立した SPA(シングルページアプリケーション)であり、|Fess| 本体の + JSP には依存しません。新しくテーマを作成する場合は、こちらの方法を推奨します。 + +JAR テーマプラグイン(レガシー) + ``view`` / ``css`` / ``js`` / ``images`` を上書きする従来型のプラグインです。 + JAR としてビルドし、プラグインとしてインストールします。既存の JSP ベースの + 画面を部分的に差し替えたい場合に使用します。 + +.. note:: + + 静的テーマは |Fess| 15.7 以降で利用できます。15.6 以前を対象とする場合は、 + JAR テーマプラグインを使用してください。検索画面の JSP・CSS・画像を管理画面から + 直接編集する方法については、:doc:`../admin/design-guide` を参照してください。 + +静的テーマ ========== +静的テーマは、``theme.yml`` マニフェストと ``index.html`` を含む静的リソースの +集合です。テーマ本体は |Fess| の ``/api/v2/*`` API を呼び出すフロントエンド +アプリケーションとして実装します。 + +構造 +---- + +静的テーマは、次のようなディレクトリ構成になります。 + :: - fess-theme-example/ - ├── pom.xml - └── src/main/resources/ - └── theme/example/ - ├── css/ - │ ├── style.css - │ └── custom.css - ├── js/ - │ └── custom.js - ├── images/ - │ └── logo.png - └── templates/ - └── search.html - -基本的なテーマ作成 -================== - -CSSカスタマイズ ---------------- - -``css/style.css``: - -.. code-block:: css - - /* ヘッダーのカスタマイズ */ - .navbar { - background-color: #1a237e; - } - - /* 検索ボックスのスタイル */ - .search-box { - border-radius: 25px; - box-shadow: 0 2px 5px rgba(0,0,0,0.2); - } - - /* 検索結果のスタイル */ - .search-result-item { - border-left: 3px solid #1a237e; - padding-left: 15px; - } - -ロゴの変更 + example/ + ├── theme.yml # マニフェスト(必須) + ├── index.html # SPA のエントリー HTML + ├── assets/ # JavaScript・CSS などの静的リソース + │ └── styles.css + ├── i18n/ # 多言語メッセージ(messages..json) + │ └── messages.en.json + ├── help/ # ヘルプ定義(.json) + │ └── en.json + └── thumbnail.png # プレビュー画像(任意) + +マニフェスト (theme.yml) +------------------------ + +``theme.yml`` は ZIP のルートに配置する必須のマニフェストです。以下は最小構成の +例です。 + +.. code-block:: yaml + + apiVersion: fess.codelibs.org/v1 + kind: StaticTheme + name: example + displayName: "Example Theme" + version: "1.0.0" + minFessVersion: "15.7" + entry: index.html + spaFallback: true + +指定できるフィールドは以下のとおりです。 + +.. list-table:: + :header-rows: 1 + :widths: 22 12 66 + + * - フィールド + - 必須 + - 説明 + * - ``apiVersion`` + - 必須 + - 固定値 ``fess.codelibs.org/v1``。 + * - ``kind`` + - 必須 + - 固定値 ``StaticTheme``。 + * - ``name`` + - 必須 + - テーマ名。``^[a-z0-9][a-z0-9_-]{0,63}$`` に一致する必要があります。 + ``themes/`` 配下に展開されるテーマのディレクトリ名(アップロード時は + この ``name`` から自動的に決まります)、および配信 URL + (``/themes//``)に使用されます。 + * - ``displayName`` + - 必須 + - 管理画面に表示される名前。 + * - ``version`` + - 必須 + - セマンティックバージョニング形式(例: ``1.0.0``、``1.2.3-beta.1``)。 + * - ``author`` + - 任意 + - 作者名。 + * - ``description`` + - 任意 + - テーマの説明。 + * - ``license`` + - 任意 + - ライセンス。 + * - ``homepage`` + - 任意 + - ホームページ URL。 + * - ``minFessVersion`` + - 任意 + - テーマが対応する |Fess| の最小バージョン。 + * - ``supportedLocales`` + - 任意 + - 対応ロケールの一覧(例: ``[en, ja, de]``)。 + * - ``entry`` + - 任意 + - SPA のエントリー HTML。既定値は ``index.html``。 + * - ``spaFallback`` + - 任意 + - SPA フォールバックの有効・無効。既定値は ``true``。 + +.. note:: + + ZIP からアップロードする場合、展開先のディレクトリ名は ``name`` から自動的に + 決まります。``themes/`` ディレクトリに手動でテーマを配置する場合は、ディレクトリ名を + ``name`` と一致させてください。一致しないテーマは再スキャン時に無視されます。 + +.. note:: + + プレビュー用のサムネイルは、テーマのルートに ``thumbnail.png`` という固定名で + 配置します(管理画面のテーマ一覧で表示されます)。この画像はマニフェストの + フィールドではなく、ファイル名で認識されます。サイズは 512KB 以内・512×512 + ピクセル以内を推奨します。 + +配信と API ---------- -1. カスタムロゴを ``images/logo.png`` に配置 -2. CSSでロゴを参照: +- 静的テーマは ``/themes//`` 配下で配信されます(```` は + ``theme.yml`` の ``name``)。 +- ``spaFallback`` が有効な場合、``/``、``/search``、``/help``、``/error``、 + ``/profile``、``/cache``、``/chat`` の各パスでエントリー HTML(既定は + ``index.html``)が返され、以降のルーティングは SPA が行います。 +- 管理画面(``/admin/*``)、``/api/*``、ログイン画面などは静的テーマの対象外で、 + |Fess| 本体が処理します。 +- テーマの SPA は、検索結果やチャットなどのデータを ``/api/v2/*`` API から取得 + します。 + +パッケージング +-------------- + +`fess-themes `__ リポジトリの +``scripts/package.sh`` を使用すると、テーマを配布用の ZIP にまとめられます。 + +:: + + ./scripts/package.sh example + +``dist/example-.zip`` が生成されます(```` は ``theme.yml`` の +``version``)。 + +.. note:: + + ``theme.yml`` は ZIP のルートに配置する必要があります。サブディレクトリに + 入れると、アップロード時に認識されません。 -.. code-block:: css +インストールと有効化 +-------------------- - .logo img { - content: url("../images/logo.png"); - max-height: 40px; - } +1. 管理画面で「システム」→「テーマ」(``/admin/theme/``)を開きます。 +2. 作成した ZIP ファイルをアップロードします。 +3. 一覧ページの「デフォルトテーマ」プルダウンから対象テーマを選び、「設定」ボタンを + 押して有効化します。 -テンプレートのカスタマイズ --------------------------- +有効化の仕組みは以下のとおりです。 -テンプレートはJSP形式です。 +- 「設定」ボタンを押すと、選択したテーマ名がシステムプロパティ ``theme.default`` + に保存され、システム全体の既定テーマになります。 +- テーマ名を仮想ホストのキーと一致させると、その仮想ホストにアクセスしたときだけ + テーマが適用されます。これにより、仮想ホストごとにテーマを切り替えられます。 +- ディスク上の ``themes/`` ディレクトリを直接更新した場合は、「再読み込み」で + 再スキャンできます。 -``templates/search.html`` (一部): +.. note:: -.. code-block:: html + ZIP のアップロードには、ファイルサイズ・展開後の合計サイズ・エントリー数などの + 上限があり、``fess_config.properties`` の ``theme.*`` プロパティで調整できます + (例: ``theme.upload.max.size`` は既定 50MB、``theme.directory.path`` は既定 + ``themes``)。展開時には ZIP Slip や zip bomb を防ぐための検証が行われます。 -
-

カスタム検索ポータル

-

社内ドキュメントを検索

-
+JAR テーマプラグイン(レガシー) +================================ -テーマの登録 -============ +JAR テーマプラグインは、|Fess| 本体の ``view`` / ``css`` / ``js`` / ``images`` +ディレクトリをテーマ名ごとに上書きするプラグインです。プラグインの一般的な構造や +ビルド方法については :doc:`plugin-architecture` も参照してください。 + +構造 +---- + +:: + + fess-theme-example/ + ├── pom.xml + └── src/main/resources/ + ├── view/ # JSP ファイル(search.jsp, index.jsp, header.jsp など) + ├── css/ # CSS ファイル(style.css など) + ├── js/ # JavaScript ファイル + └── images/ # 画像ファイル(logo.png など) + +.. note:: + + ビュー(テンプレート)は JSP 形式です。リソースの最上位ディレクトリは + ``view`` / ``css`` / ``js`` / ``images`` の 4 つのみが認識されます。 + アーティファクト名は ``fess-theme-`` で始まる必要があります。 pom.xml ------- +プラグインは ``fess-parent`` を親 POM とする jar としてビルドします。テーマは +リソースのみで構成されるため、通常は追加の依存関係を宣言する必要はありません。 + .. code-block:: xml - org.codelibs.fess - fess-theme-example - 15.8.0 - jar + + + 4.0.0 -設定ファイル ------------- + fess-theme-example + 15.8.0 + jar -``src/main/resources/theme.properties``: + + org.codelibs.fess + fess-parent + 15.8.0 + + + -:: +CSS・画像のカスタマイズ +----------------------- - theme.name=example - theme.display.name=Example Theme - theme.version=1.0.0 +検索画面は Bootstrap ベースの JSP で構成されています。CSS を上書きして配色や +レイアウトを変更したり、``images/logo.png`` を差し替えてロゴを変更したりできます。 +対象となるクラス名やマークアップは、実際の JSP(``view/index.jsp`` / +``view/search.jsp`` など)を確認してください。 -インストール -============ +ビルドとインストール +-------------------- :: - ./bin/fess-plugin install fess-theme-example + mvn clean package + +``target/`` ディレクトリに JAR ファイル(例: ``fess-theme-example-15.8.0.jar``)が +生成されます。管理画面の「システム」→「プラグイン」からインストールできます。 +インストール手順の詳細は :doc:`../admin/plugin-guide` を参照してください。 + +インストールすると、JAR 内の各ディレクトリはテーマ名ごとに以下の場所へ展開されます +(テーマ名はアーティファクト名から ``fess-theme-`` を除いた部分。上記の例では +``example``)。 + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - JAR 内のディレクトリ + - 展開先 + * - ``view/`` + - ``WEB-INF/view//`` + * - ``css/`` + - ``css//`` + * - ``js/`` + - ``js//`` + * - ``images/`` + - ``images//`` + +有効化 +------ + +JAR テーマは、仮想ホスト機能を使って有効化します。仮想ホストのキーをテーマ名に +一致させると、そのホストへのアクセスでテーマが適用されます。 -管理画面からテーマを選択: +1. 「システム」→「全般」の仮想ホスト設定で、``Host:localhost:8080=example`` の + ように、リクエストの ``Host`` ヘッダーとテーマ名(仮想ホストのキー)を対応付けます。 +2. 必要に応じて、クローリングの Web 設定などの仮想ホストにも同じ名前(``example``)を + 設定します。 -1. 「システム」→「デザイン」 -2. テーマを選択 -3. 保存して適用 +仮想ホストの設定方法の詳細は :doc:`../admin/general-guide` を参照してください。 既存テーマの例 ============== -- `fess-theme-simple `__ -- `fess-theme-minimal `__ +- `fess-themes `__ - 静的テーマ集 + (``codesearch``、``docsearch`` など複数の静的テーマを収録) +- `fess-theme-simple `__ - JAR テーマ +- `fess-theme-classic `__ - JAR テーマ 参考情報 ======== - :doc:`plugin-architecture` - プラグインアーキテクチャ -- :doc:`../admin/design-guide` - デザイン設定ガイド +- :doc:`../admin/design-guide` - ページのデザイン(JSP・CSS・画像の直接編集) +- :doc:`../admin/plugin-guide` - プラグインのインストール diff --git a/ko/15.8/dev/theme-development.rst b/ko/15.8/dev/theme-development.rst index e0396db9..17079b7d 100644 --- a/ko/15.8/dev/theme-development.rst +++ b/ko/15.8/dev/theme-development.rst @@ -5,127 +5,303 @@ 개요 ==== -|Fess|의 테마 시스템을 사용하여 검색 화면 디자인을 커스터마이즈할 수 있습니다. -테마는 플러그인으로 배포할 수 있으며, 여러 테마를 전환하여 사용할 수 있습니다. +|Fess| 에서는 검색 화면의 디자인을 다음 2 가지 방법으로 커스터마이징할 수 있습니다. -테마 구조 +정적 테마 (Static Theme) + |Fess| 15.7 에서 도입된 방식입니다. 테마를 ZIP 파일로 배포하고, + 관리 화면에서 업로드하여 활성화합니다. 테마 본체는 ``/api/v2/*`` API 를 + 이용하는 독립된 SPA(싱글 페이지 애플리케이션)이며, |Fess| 본체의 + JSP 에 의존하지 않습니다. 새로 테마를 만드는 경우에는 이 방법을 권장합니다. + +JAR 테마 플러그인(레거시) + ``view`` / ``css`` / ``js`` / ``images`` 를 덮어쓰는 기존 방식의 플러그인입니다. + JAR 로 빌드하여 플러그인으로 설치합니다. 기존 JSP 기반의 + 화면을 부분적으로 교체하고 싶은 경우에 사용합니다. + +.. note:: + + 정적 테마는 |Fess| 15.7 이후 버전에서 사용할 수 있습니다. 15.6 이전 버전을 + 대상으로 하는 경우에는 JAR 테마 플러그인을 사용하십시오. 검색 화면의 + JSP·CSS·이미지를 관리 화면에서 직접 편집하는 방법에 대해서는 + :doc:`../admin/design-guide` 를 참조하십시오. + +정적 테마 ========== +정적 테마는 ``theme.yml`` 매니페스트와 ``index.html`` 을 포함하는 정적 리소스의 +집합입니다. 테마 본체는 |Fess| 의 ``/api/v2/*`` API 를 호출하는 프런트엔드 +애플리케이션으로 구현합니다. + +구조 +---- + +정적 테마는 다음과 같은 디렉터리 구성을 가집니다. + :: - fess-theme-example/ - ├── pom.xml - └── src/main/resources/ - └── theme/example/ - ├── css/ - │ ├── style.css - │ └── custom.css - ├── js/ - │ └── custom.js - ├── images/ - │ └── logo.png - └── templates/ - └── search.html - -기본 테마 작성 -================== - -CSS 커스터마이즈 ---------------- - -``css/style.css``: - -.. code-block:: css - - /* 헤더 커스터마이즈 */ - .navbar { - background-color: #1a237e; - } - - /* 검색 박스 스타일 */ - .search-box { - border-radius: 25px; - box-shadow: 0 2px 5px rgba(0,0,0,0.2); - } - - /* 검색 결과 스타일 */ - .search-result-item { - border-left: 3px solid #1a237e; - padding-left: 15px; - } - -로고 변경 + example/ + ├── theme.yml # 매니페스트(필수) + ├── index.html # SPA 엔트리 HTML + ├── assets/ # JavaScript·CSS 등 정적 리소스 + │ └── styles.css + ├── i18n/ # 다국어 메시지(messages..json) + │ └── messages.en.json + ├── help/ # 도움말 정의(.json) + │ └── en.json + └── thumbnail.png # 미리보기 이미지(임의) + +매니페스트 (theme.yml) +------------------------ + +``theme.yml`` 은 ZIP 의 루트에 배치하는 필수 매니페스트입니다. 다음은 최소 구성의 +예입니다. + +.. code-block:: yaml + + apiVersion: fess.codelibs.org/v1 + kind: StaticTheme + name: example + displayName: "Example Theme" + version: "1.0.0" + minFessVersion: "15.7" + entry: index.html + spaFallback: true + +지정할 수 있는 필드는 다음과 같습니다. + +.. list-table:: + :header-rows: 1 + :widths: 22 12 66 + + * - 필드 + - 필수 + - 설명 + * - ``apiVersion`` + - 필수 + - 고정값 ``fess.codelibs.org/v1``. + * - ``kind`` + - 필수 + - 고정값 ``StaticTheme``. + * - ``name`` + - 필수 + - 테마 이름. ``^[a-z0-9][a-z0-9_-]{0,63}$`` 에 일치해야 합니다. + ``themes/`` 아래에 전개되는 테마의 디렉터리 이름(업로드 시에는 + 이 ``name`` 으로 자동으로 결정됩니다), 그리고 배포 URL + (``/themes//``)에 사용됩니다. + * - ``displayName`` + - 필수 + - 관리 화면에 표시되는 이름. + * - ``version`` + - 필수 + - 시맨틱 버저닝 형식(예: ``1.0.0``, ``1.2.3-beta.1``). + * - ``author`` + - 선택 + - 작성자 이름. + * - ``description`` + - 선택 + - 테마 설명. + * - ``license`` + - 선택 + - 라이선스. + * - ``homepage`` + - 선택 + - 홈페이지 URL. + * - ``minFessVersion`` + - 선택 + - 테마가 지원하는 |Fess| 의 최소 버전. + * - ``supportedLocales`` + - 선택 + - 지원 로케일 목록(예: ``[en, ja, de]``). + * - ``entry`` + - 선택 + - SPA 엔트리 HTML. 기본값은 ``index.html``. + * - ``spaFallback`` + - 선택 + - SPA 폴백(fallback)의 활성화·비활성화 여부. 기본값은 ``true``. + +.. note:: + + ZIP 에서 업로드하는 경우, 전개될 디렉터리 이름은 ``name`` 으로 자동으로 + 결정됩니다. ``themes/`` 디렉터리에 수동으로 테마를 배치하는 경우에는 디렉터리 + 이름을 ``name`` 과 일치시켜 주십시오. 일치하지 않는 테마는 재스캔 시 무시됩니다. + +.. note:: + + 미리보기용 썸네일은 테마의 루트에 ``thumbnail.png`` 라는 고정된 이름으로 + 배치합니다(관리 화면의 테마 목록에 표시됩니다). 이 이미지는 매니페스트의 + 필드가 아니라 파일 이름으로 인식됩니다. 크기는 512KB 이내·512×512 + 픽셀 이내를 권장합니다. + +배포와 API ---------- -1. 커스텀 로고를 ``images/logo.png``에 배치 -2. CSS로 로고 참조: +- 정적 테마는 ``/themes//`` 아래에서 배포됩니다(```` 은 + ``theme.yml`` 의 ``name``). +- ``spaFallback`` 이 활성화된 경우, ``/``, ``/search``, ``/help``, ``/error``, + ``/profile``, ``/cache``, ``/chat`` 의 각 경로에서 엔트리 HTML(기본값은 + ``index.html``)이 반환되며, 이후의 라우팅은 SPA 가 담당합니다. +- 관리 화면(``/admin/*``), ``/api/*``, 로그인 화면 등은 정적 테마의 대상 외이며, + |Fess| 본체가 처리합니다. +- 테마의 SPA 는 검색 결과나 채팅 등의 데이터를 ``/api/v2/*`` API 에서 가져옵니다. + +패키징 +-------------- + +`fess-themes `__ 리포지토리의 +``scripts/package.sh`` 를 사용하면 테마를 배포용 ZIP 으로 묶을 수 있습니다. + +:: + + ./scripts/package.sh example + +``dist/example-.zip`` 이 생성됩니다(```` 은 ``theme.yml`` 의 +``version``). + +.. note:: + + ``theme.yml`` 은 ZIP 의 루트에 배치해야 합니다. 하위 디렉터리에 + 넣으면 업로드 시 인식되지 않습니다. -.. code-block:: css +설치와 활성화 +-------------------- - .logo img { - content: url("../images/logo.png"); - max-height: 40px; - } +1. 관리 화면에서 [시스템 > 테마](``/admin/theme/``)를 엽니다. +2. 작성한 ZIP 파일을 업로드합니다. +3. 목록 페이지의 「기본 테마」 드롭다운에서 대상 테마를 선택하고, 「설정」 버튼을 + 눌러 활성화합니다. -템플릿 커스터마이즈 --------------------------- +활성화의 원리는 다음과 같습니다. -템플릿은 JSP 형식입니다. +- 「설정」 버튼을 누르면 선택한 테마 이름이 시스템 프로퍼티 ``theme.default`` + 에 저장되어 시스템 전체의 기본 테마가 됩니다. +- 테마 이름을 가상 호스트의 키와 일치시키면, 해당 가상 호스트에 접속했을 때만 + 테마가 적용됩니다. 이를 통해 가상 호스트별로 테마를 전환할 수 있습니다. +- 디스크상의 ``themes/`` 디렉터리를 직접 갱신한 경우에는 「다시 로드」로 + 재스캔할 수 있습니다. -``templates/search.html`` (일부): +.. note:: -.. code-block:: html + ZIP 업로드에는 파일 크기·전개 후 총 크기·엔트리 수 등의 상한이 있으며, + ``fess_config.properties`` 의 ``theme.*`` 프로퍼티로 조정할 수 있습니다 + (예: ``theme.upload.max.size`` 는 기본값 50MB, ``theme.directory.path`` 는 + 기본값 ``themes``). 전개 시에는 ZIP Slip 이나 zip bomb 을 방지하기 위한 + 검증이 이루어집니다. -
-

커스텀 검색 포털

-

사내 문서 검색

-
+JAR 테마 플러그인(레거시) +================================ -테마 등록 -============ +JAR 테마 플러그인은 |Fess| 본체의 ``view`` / ``css`` / ``js`` / ``images`` +디렉터리를 테마 이름별로 덮어쓰는 플러그인입니다. 플러그인의 일반적인 구조나 +빌드 방법에 대해서는 :doc:`plugin-architecture` 도 참조하십시오. + +구조 +---- + +:: + + fess-theme-example/ + ├── pom.xml + └── src/main/resources/ + ├── view/ # JSP 파일(search.jsp, index.jsp, header.jsp 등) + ├── css/ # CSS 파일(style.css 등) + ├── js/ # JavaScript 파일 + └── images/ # 이미지 파일(logo.png 등) + +.. note:: + + 뷰(템플릿)는 JSP 형식입니다. 리소스의 최상위 디렉터리는 + ``view`` / ``css`` / ``js`` / ``images`` 의 4 가지만 인식됩니다. + 아티팩트 이름은 ``fess-theme-`` 로 시작해야 합니다. pom.xml ------- +플러그인은 ``fess-parent`` 를 부모 POM 으로 하는 jar 로 빌드합니다. 테마는 +리소스만으로 구성되므로, 일반적으로 추가 의존 관계를 선언할 필요는 없습니다. + .. code-block:: xml - org.codelibs.fess - fess-theme-example - 15.8.0 - jar + + + 4.0.0 -설정 파일 ------------- + fess-theme-example + 15.8.0 + jar -``src/main/resources/theme.properties``: + + org.codelibs.fess + fess-parent + 15.8.0 + + + -:: +CSS·이미지 커스터마이징 +----------------------- - theme.name=example - theme.display.name=Example Theme - theme.version=1.0.0 +검색 화면은 Bootstrap 기반의 JSP 로 구성되어 있습니다. CSS 를 덮어써서 배색이나 +레이아웃을 변경하거나, ``images/logo.png`` 를 교체하여 로고를 변경할 수 있습니다. +대상이 되는 클래스 이름이나 마크업은 실제 JSP(``view/index.jsp`` / +``view/search.jsp`` 등)를 확인하십시오. -설치 -============ +빌드와 설치 +-------------------- :: - ./bin/fess-plugin install fess-theme-example + mvn clean package + +``target/`` 디렉터리에 JAR 파일(예: ``fess-theme-example-15.8.0.jar``)이 +생성됩니다. 관리 화면의 [시스템 > 플러그인]에서 설치할 수 있습니다. +설치 절차의 자세한 내용은 :doc:`../admin/plugin-guide` 를 참조하십시오. + +설치하면 JAR 내의 각 디렉터리는 테마 이름별로 다음 위치에 전개됩니다 +(테마 이름은 아티팩트 이름에서 ``fess-theme-`` 를 제외한 부분입니다. 위 예에서는 +``example``). + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - JAR 내 디렉터리 + - 전개 위치 + * - ``view/`` + - ``WEB-INF/view//`` + * - ``css/`` + - ``css//`` + * - ``js/`` + - ``js//`` + * - ``images/`` + - ``images//`` + +활성화 +------ + +JAR 테마는 가상 호스트 기능을 사용하여 활성화합니다. 가상 호스트의 키를 테마 +이름과 일치시키면, 해당 호스트로의 접속 시 테마가 적용됩니다. -관리 화면에서 테마 선택: +1. [시스템 > 일반]의 가상 호스트 설정에서 ``Host:localhost:8080=example`` 과 + 같이, 요청의 ``Host`` 헤더와 테마 이름(가상 호스트의 키)을 대응시킵니다. +2. 필요에 따라 크롤링의 웹 설정 등의 가상 호스트에도 같은 이름(``example``)을 + 설정합니다. -1. "시스템" -> "디자인" -2. 테마 선택 -3. 저장하여 적용 +가상 호스트 설정 방법의 자세한 내용은 :doc:`../admin/general-guide` 를 참조하십시오. -기존 테마 예 +기존 테마 예시 ============== -- `fess-theme-simple `__ -- `fess-theme-minimal `__ +- `fess-themes `__ - 정적 테마 모음집 + (``codesearch``, ``docsearch`` 등 여러 정적 테마 수록) +- `fess-theme-simple `__ - JAR 테마 +- `fess-theme-classic `__ - JAR 테마 참고 정보 ======== - :doc:`plugin-architecture` - 플러그인 아키텍처 -- :doc:`../admin/design-guide` - 디자인 설정 가이드 +- :doc:`../admin/design-guide` - 페이지 디자인(JSP·CSS·이미지 직접 편집) +- :doc:`../admin/plugin-guide` - 플러그인 설치 diff --git a/zh-cn/15.8/dev/theme-development.rst b/zh-cn/15.8/dev/theme-development.rst index 93184c2a..a2142d63 100644 --- a/zh-cn/15.8/dev/theme-development.rst +++ b/zh-cn/15.8/dev/theme-development.rst @@ -5,128 +5,295 @@ 概述 ==== -使用 |Fess| 的主题系统，您可以自定义搜索界面的设计。 -主题可以作为插件分发，并支持多主题切换使用。 +通过 |Fess|，可以使用以下两种方法自定义搜索界面的设计。 -主题结构 +静态主题（Static Theme） + 这是 |Fess| 15.7 中引入的机制。将主题以 ZIP 文件的形式分发， + 从管理界面上传后即可启用。主题本体是使用 ``/api/v2/*`` API 的独立 SPA + （单页应用程序），不依赖于 |Fess| 本体的 JSP。如果要新建主题， + 推荐使用这种方法。 + +JAR 主题插件（旧版） + 这是一种覆盖 ``view`` / ``css`` / ``js`` / ``images`` 的传统类型插件。 + 构建为 JAR 后作为插件安装。适用于希望对现有的基于 JSP 的界面进行 + 部分替换的场景。 + +.. note:: + + 静态主题可在 |Fess| 15.7 及以上版本中使用。如果目标版本为 15.6 及更早版本， + 请使用 JAR 主题插件。关于从管理界面直接编辑搜索界面的 JSP、CSS、图像的方法， + 请参考 :doc:`../admin/design-guide`。 + +静态主题 ======== -:: +静态主题是包含 ``theme.yml`` 清单文件和 ``index.html`` 的一组静态资源。 +主题本体作为调用 |Fess| 的 ``/api/v2/*`` API 的前端应用程序来实现。 - fess-theme-example/ - ├── pom.xml - └── src/main/resources/ - └── theme/example/ - ├── css/ - │ ├── style.css - │ └── custom.css - ├── js/ - │ └── custom.js - ├── images/ - │ └── logo.png - └── templates/ - └── search.html - -基本主题创建 -============ +结构 +---- -CSS自定义 ---------- +静态主题采用如下目录结构。 -``css/style.css``: +:: + + example/ + ├── theme.yml # 清单文件(必需) + ├── index.html # SPA 的入口 HTML + ├── assets/ # JavaScript、CSS 等静态资源 + │ └── styles.css + ├── i18n/ # 多语言消息(messages..json) + │ └── messages.en.json + ├── help/ # 帮助定义(.json) + │ └── en.json + └── thumbnail.png # 预览图片(可选) + +清单文件（theme.yml） +--------------------- + +``theme.yml`` 是必须放置在 ZIP 根目录下的清单文件。以下是最小配置的 +示例。 + +.. code-block:: yaml + + apiVersion: fess.codelibs.org/v1 + kind: StaticTheme + name: example + displayName: "Example Theme" + version: "1.0.0" + minFessVersion: "15.7" + entry: index.html + spaFallback: true + +可以指定的字段如下。 + +.. list-table:: + :header-rows: 1 + :widths: 22 12 66 + + * - 字段 + - 必需 + - 说明 + * - ``apiVersion`` + - 必需 + - 固定值 ``fess.codelibs.org/v1``。 + * - ``kind`` + - 必需 + - 固定值 ``StaticTheme``。 + * - ``name`` + - 必需 + - 主题名称。必须匹配 ``^[a-z0-9][a-z0-9_-]{0,63}$``。 + 用作展开到 ``themes/`` 下的主题目录名（上传时该名称会根据 + ``name`` 自动确定），以及分发 URL（``/themes//``）。 + * - ``displayName`` + - 必需 + - 显示在管理界面中的名称。 + * - ``version`` + - 必需 + - 语义化版本格式（例如：``1.0.0``、``1.2.3-beta.1``）。 + * - ``author`` + - 可选 + - 作者姓名。 + * - ``description`` + - 可选 + - 主题说明。 + * - ``license`` + - 可选 + - 许可证。 + * - ``homepage`` + - 可选 + - 主页 URL。 + * - ``minFessVersion`` + - 可选 + - 主题所支持的 |Fess| 最低版本。 + * - ``supportedLocales`` + - 可选 + - 支持的区域设置列表（例如：``[en, ja, de]``）。 + * - ``entry`` + - 可选 + - SPA 的入口 HTML。默认值为 ``index.html``。 + * - ``spaFallback`` + - 可选 + - 是否启用 SPA 回退。默认值为 ``true``。 + +.. note:: + + 如果从 ZIP 上传，展开目标的目录名会根据 ``name`` 自动确定。如果要在 + ``themes/`` 目录中手动放置主题，请使目录名与 ``name`` 保持一致。 + 名称不一致的主题在重新扫描时会被忽略。 + +.. note:: + + 用于预览的缩略图，需以 ``thumbnail.png`` 这一固定文件名放置在主题的 + 根目录下（会显示在管理界面的主题列表中）。该图片并非通过清单文件的 + 字段来识别，而是通过文件名来识别。建议大小控制在 512KB 以内、 + 尺寸控制在 512×512 像素以内。 + +分发与 API +---------- -.. code-block:: css +- 静态主题在 ``/themes//`` 下分发（```` 为 ``theme.yml`` + 中的 ``name``）。 +- 当 ``spaFallback`` 启用时，在 ``/``、``/search``、``/help``、``/error``、 + ``/profile``、``/cache``、``/chat`` 等各个路径下都会返回入口 HTML + （默认是 ``index.html``），此后的路由由 SPA 处理。 +- 管理界面（``/admin/*``）、``/api/*``、登录界面等不属于静态主题的处理 + 范围，而是由 |Fess| 本体处理。 +- 主题的 SPA 会通过 ``/api/v2/*`` API 获取搜索结果、聊天等数据。 - /* 头部自定义 */ - .navbar { - background-color: #1a237e; - } +打包 +---- - /* 搜索框样式 */ - .search-box { - border-radius: 25px; - box-shadow: 0 2px 5px rgba(0,0,0,0.2); - } +使用 `fess-themes `__ 仓库中的 +``scripts/package.sh``，可以将主题打包成用于分发的 ZIP 文件。 - /* 搜索结果样式 */ - .search-result-item { - border-left: 3px solid #1a237e; - padding-left: 15px; - } +:: -更改Logo --------- + ./scripts/package.sh example -1. 将自定义Logo放置到 ``images/logo.png`` -2. 在CSS中引用Logo: +会生成 ``dist/example-.zip``（```` 为 ``theme.yml`` 中的 +``version``）。 -.. code-block:: css +.. note:: - .logo img { - content: url("../images/logo.png"); - max-height: 40px; - } + ``theme.yml`` 必须放置在 ZIP 的根目录下。如果放在子目录中， + 上传时将无法被识别。 -模板自定义 +安装与启用 ---------- -模板为JSP格式。 +1. 在管理界面打开"系统"→"主题"（``/admin/theme/``）。 +2. 上传创建好的 ZIP 文件。 +3. 在列表页面的"默认主题"下拉菜单中选择目标主题，点击"设置"按钮启用。 -``templates/search.html`` (部分): +启用机制如下所述。 -.. code-block:: html +- 点击"设置"按钮后，所选的主题名称会保存到系统属性 ``theme.default`` + 中，成为系统整体的默认主题。 +- 如果使主题名称与虚拟主机的键一致，则仅在访问该虚拟主机时才会应用该 + 主题。由此可以按虚拟主机切换主题。 +- 如果直接更新了磁盘上的 ``themes/`` 目录，可以通过"重新加载"来重新 + 扫描。 -
-

自定义搜索门户

-

搜索内部文档

-
+.. note:: -主题注册 -======== + ZIP 上传存在文件大小、展开后总大小、条目数量等方面的上限，可通过 + ``fess_config.properties`` 中的 ``theme.*`` 属性进行调整（例如： + ``theme.upload.max.size`` 默认为 50MB，``theme.directory.path`` 默认为 + ``themes``）。展开时会执行防止 ZIP Slip 和 zip bomb 的校验。 + +JAR 主题插件（旧版） +==================== + +JAR 主题插件是按主题名称覆盖 |Fess| 本体的 ``view`` / ``css`` / ``js`` / +``images`` 目录的插件。关于插件的一般结构和构建方法，也请参考 +:doc:`plugin-architecture`。 + +结构 +---- + +:: + + fess-theme-example/ + ├── pom.xml + └── src/main/resources/ + ├── view/ # JSP 文件(search.jsp, index.jsp, header.jsp 等) + ├── css/ # CSS 文件(style.css 等) + ├── js/ # JavaScript 文件 + └── images/ # 图片文件(logo.png 等) + +.. note:: + + 视图（模板）为 JSP 格式。资源的顶层目录仅识别 ``view`` / ``css`` / + ``js`` / ``images`` 这 4 个。构件名称必须以 ``fess-theme-`` 开头。 pom.xml ------- +插件以 ``fess-parent`` 作为父 POM，构建为 jar。由于主题仅由资源构成， +通常不需要声明额外的依赖关系。 + .. code-block:: xml - org.codelibs.fess - fess-theme-example - 15.8.0 - jar + + + 4.0.0 + + fess-theme-example + 15.8.0 + jar + + + org.codelibs.fess + fess-parent + 15.8.0 + + + + +CSS 与图片的自定义 +------------------ + +搜索界面由基于 Bootstrap 的 JSP 构成。可以通过覆盖 CSS 来更改配色和 +布局，或者替换 ``images/logo.png`` 来更改徽标。关于具体的类名和标记， +请查看实际的 JSP（``view/index.jsp`` / ``view/search.jsp`` 等）。 + +构建与安装 +---------- -配置文件 --------- +:: -``src/main/resources/theme.properties``: + mvn clean package -:: +会在 ``target/`` 目录下生成 JAR 文件（例如：``fess-theme-example-15.8.0.jar``）。 +可以从管理界面的"系统"→"插件"进行安装。安装步骤的详细信息请参考 +:doc:`../admin/plugin-guide`。 - theme.name=example - theme.display.name=Example Theme - theme.version=1.0.0 +安装后，JAR 内的各个目录会按主题名称展开到以下位置（主题名称是从构件 +名称中去掉 ``fess-theme-`` 后的部分。在上述示例中为 ``example``）。 -安装 -==== +.. list-table:: + :header-rows: 1 + :widths: 30 70 -:: + * - JAR 内的目录 + - 展开位置 + * - ``view/`` + - ``WEB-INF/view//`` + * - ``css/`` + - ``css//`` + * - ``js/`` + - ``js//`` + * - ``images/`` + - ``images//`` - ./bin/fess-plugin install fess-theme-example +启用 +---- -从管理界面选择主题: +JAR 主题通过虚拟主机功能来启用。如果使虚拟主机的键与主题名称一致， +则访问该主机时会应用该主题。 -1. "系统" -> "设计" -2. 选择主题 -3. 保存并应用 +1. 在"系统"→"通用"的虚拟主机设置中，按照 ``Host:localhost:8080=example`` + 这样的格式，将请求的 ``Host`` 请求头与主题名称（虚拟主机的键）对应 + 起来。 +2. 根据需要，也在爬取的 Web 设置等虚拟主机中设置相同的名称（``example``）。 + +关于虚拟主机的设置方法详情，请参考 :doc:`../admin/general-guide`。 现有主题示例 ============ -- `fess-theme-simple `__ -- `fess-theme-minimal `__ +- `fess-themes `__ - 静态主题集 + （收录了 ``codesearch``、``docsearch`` 等多个静态主题） +- `fess-theme-simple `__ - JAR 主题 +- `fess-theme-classic `__ - JAR 主题 参考信息 ======== - :doc:`plugin-architecture` - 插件架构 -- :doc:`../admin/design-guide` - 设计设置指南 - +- :doc:`../admin/design-guide` - 页面设计（直接编辑 JSP、CSS、图片） +- :doc:`../admin/plugin-guide` - 插件安装