Webサイトへのインストール

この検索エンジンには、jQueryをベースにした基本的なウェブインタフェースとスタイルシートが含まれています。このドキュメントでは、ウェブサイトにこのインタフェースをインストールする方法を紹介します。

ノート

世界中にはさまざまな形式のHTMLがあります。この検索エンジンはまだできたばかりで、ほんの少しのウェブサイトでしか稼働実績がありません。もしHTMLファイルの構造がこのドキュメントで想定しているものと大きく異る場合は、インタフェーススクリプトを変更する必要があるかもしれません。

基本的なフォルダ構造

下記の構造が想定している基本的な構造です:

[document root]
  + index.html
  + search/
  |  + oktavia-search.js or oktavia-*-search.js
  |  + oktavia-jquery-ui.js
  |  + jquery.js
  |  + searchindex.js
  |  + oktavia-jquery-highlight.js (optional)
  + searchstyle.css
  + [other contents]

ドメインのトップ、もしくはディレクトリのどちらもドキュメントルートに設定することができます:

ドメインルート: http://example.com/
サブドメインのルート: http://doc.example.com/
ディレクトリ: http://example.com/doc/

次の5つのファイルをフォルダに追加します:

oktavia-search.js もしくは oktavia-*-search.js

これは検索エンジンのコアコンポーネントです。これらはリポジトリの lib フォルダにあります。 oktavia-search.js は標準版です。他の物は標準版にステミングの機能を追加したものです。例えば、 oktavia-german-search.js はドイツ語のステミングライブラリが追加されています。
oktavia-jquery-ui.js

これは検索エンジンのウェブ用のユーザインタフェースです。検索のキーワードを検索フォームから読み取って検索エンジンに渡し、返ってきた結果をDOMに変換します。これは標準的なブラウザ用のJavaScriptのコードなのでカスタマイズも簡単にできるでしょう。
jquery.js

oktavia-jquery-ui.js はDOMの操作にjQueryを利用しています。1.9.1でテストしています。
searchstyle.css

これは検索フォームと検索結果のデフォルトのスタイルが含まれています。ウェブサイトに合わせてカスタマイズする必要があるでしょう。
searchindex.js

これはドキュメントのインデックスファイルです。これは チュートリアル で説明されているインデックスと同じものです。
oktavia-jquery-highlight.js (オプション)

これはオプションのモジュールです。このモジュールは、検索結果からジャンプした先のページで検索ワードのハイライトを行います。もしSphinxかTinkererを使っているのであれば、このモジュールを追加する必要はありません。OktaviaのウェブインタフェースはSphinxと互換性のあるGETパラメータを追加します。

ノート

バージョン0.5から、検索用語ハイライト機能が追加されました。
バージョン0.5からjs出力がデフォルトになりました。明示的に -t js を指定する必要はありません。

ファイルの追加

次の内容を、検索フォームを追加したいHTMLファイルに追加します:

<link rel="stylesheet" href="searchstyle.css" type="text/css" />
<script src="search/jquery-1.9.1.min.js"></script>
<script src="search/oktavia-jquery-ui.js"></script>
<script src="search/oktavia-english-search.js"></script>

もし、Sphinx、Tinkererで生成したHTML以外のHTMLに組み込む場合で、検索用語のハイライトを追加したい場合は次の行も追加します:

<script src="search/oktavia-jquery-highlight.js"></script>

ノート

このコードサンプルはjQuery 1.9.1のミニファイ版を利用しています。より古いjQueryも使うことができます。OktaviaとjQuery 1.4との組み合わせで動作することは検証しています。

HTMLへのタグの追加と、インデックスファイルの場所の設定

これまでの説明で、必要な5つのファイルのうち4つのファイル(+オプション1ファイル)をHTMLに追加しました。残るファイルはインデックスファイルです。

この検索エンジンは大きなファイルもサポートするために(例えば、Pythonのドキュメントから作ったインデックスは6.7MBあります)、非同期のインデックスファイル読み込みをサポートしています。そのため、インデックスファイルの場所を指定する必要があります。

検索フォームの位置を設定する方法は3つあります。

特定のIDを持つタグを利用する

#oktavia_search_form が特定の名前です。もしこのIDを持つタグがあれば、ユーザインタフェースコードはそのタグを検索フォームに変換します。
```
<div id="oktavia_search_form"></div>
```
このタグに、ドキュメントルート、インデックスファイルのパス、ロゴを表示するかどうかのフラグをパラメータとして設定することができます:
```
<div id="oktavia_search_form" data-document-root="." data-index="./scripts/searchindex.js" data-logo="enabled"></div>
```
jQueryプラグインを使用:

oktavia-jquery-ui.js はjQueryプラグインも提供しています。これを使用すると、どのタグでも検索フォームに変えることができます:
```
$('#search').oktaviaSearch({
    documentRoot: '..',
    index: '../search/searchindex.js',
    logo: false
});
```
同期読み込み

検索インデックスを同期読み込みすることができます。これは一番シンプルな方法ですが、インデックスファイルのサイズが大きい場合には推奨されない方法です。
```
<script src="search/searchindex.js"></script>
```

パラメータが省略されると、次の値が使用されます:

パラメータ	デフォルト値	コメント
documentRoot	"."	これはインデックスファイル場所および、検索結果のURLを解決するのに使用されます。
index	"search/searchindex.js"	インデックスファイルのパスです。もし "." か "/" 以外の文字が先頭の場合は、ドキュメントルートからの相対パスで読み込みに行きます。
logo	true	文字列の "false" か "disabled" でないか、正の値であれば、検索エンジン名とホームページへのリンクを検索結果ウインドウの下部に表示します。

documentRoot は他の方法を使っても指定することができます:

<base> タグ

もし <base> タグをすでに使用していれば、特に何もすることはありません。インデックスファイルはこの場所からの相対パスで読み込まれます。
DOCUMENTATION_OPTIONS.URL_ROOT

ドキュメントツールの Sphinx は生成したHTMLファイルに次のタグを埋め込みます。もし DOCUMENTATION_OPTIONS というグローバル変数があれば、ウェブインタフェースはこの変数を読み込み、 DOCUMENTATION_OPTIONS + 'search/searchindex.js' を読み込みます。
```
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
    URL_ROOT:    '#',
    VERSION:     '1.0',
    COLLAPSE_MODINDEX: false,
    FILE_SUFFIX: '.html',
    HAS_SOURCE:  true
};
</script>
```

oktavia-jquery-ui.js は次のタグを、対象のタグに追加します。

<form id="oktavia_form">
    <input class="oktavia_search" type="search" name="search" value="" placeholder="Search" />
</form>
<div class="oktavia_searchresult_box">
    <div class="oktavia_close_search_box">&times;</div>
    <div class="oktavia_searchresult_summary"></div>
    <div class="oktavia_searchresult"></div>
    <div class="oktavia_searchresult_nav"></div>
    <span class="pr">Powered by <a href="http://oktavia.info">Oktavia</a></span>
</div>

Oktavia

Webサイトへのインストール

基本的なフォルダ構造

ファイルの追加

HTMLへのタグの追加と、インデックスファイルの場所の設定

ダウンロード

ニュース

最新のニュース

カテゴリ一覧

タグ一覧