Files @ 73e3599971da
Branch filter:

Location: kallithea/docs/usage/customization.rst

73e3599971da 1.7 KiB text/prs.fallenstein.rst Show Annotation Show as Raw Download as Raw
FUJIWARA Katsunori
journal: make "repository:" filtering condition work as expected (Issue #261)

Before this revision, journal filtering conditions like as below never
match against any entry, even if there are corresponded repositories.

- repository:foo/bar
- repository:foo-bar

Whoosh library, which is used to parse filtering condition, does:

- treat almost all non-alphanumeric characters as delimiter at
parsing condition
- join each conditions at filtering by "AND", by default

For example, filtering condition "repository:foo/bar" is translated as
"repository:foo AND repository:bar". This combined condition never
matches against any entry, because it is impossible that "repository"
field in DBMS table "user_logs" has both "foo" and "bar" values at
same time.

Using TEXT for "repository" of JOURNAL_SCHEMA causes this issue,
because TEXT assumes tokenization at parsing.

In addition to it, using TEXT also causes unintentional ignorance of
"stop words" in filtering conditions. For example, "this", "a", "you",
and so on are ignored at parsing, because these are too generic words
(from point of view of generic "text search").

To make "repository:" filtering condition work as expected, this
revision uses ID instead of TEST for "repository" of
JOURNAL_COLUMN. ID avoids both tokenization and removing "stop words".

This replacement should be safe with already existing DBMS instance,
because:

- JOURNAL_SCHEMA is used only to parse filtering condition
- DBMS table "user_logs" itself is defined by UserLog class
(in kallithea/model/db.py)

BTW, using ID also avoids normalization by lowercase-ing. But this
doesn't violate current case-insensitive search policy, because
LOWER-ing in actual SQL query is achieved by get_filterion() or so in
kallithea/controllers/admin/admin.py.
.. _customization:

=============
Customization
=============

There are several ways to customize Kallithea to your needs depending on what
you want to achieve.


HTML/JavaScript/CSS customization
---------------------------------

To customize the look-and-feel of the web interface (for example to add a
company banner or some JavaScript widget or to tweak the CSS style definitions)
you can enter HTML code (possibly with JavaScript and/or CSS) directly via the
*Admin > Settings > Global > HTML/JavaScript customization
block*.


Behavioral customization: rcextensions
--------------------------------------

Some behavioral customization can be done in Python using ``rcextensions``, a
custom Python package that can extend Kallithea functionality.

With ``rcextensions`` it's possible to add additional mappings for Whoosh
indexing and statistics, to add additional code into the push/pull/create/delete
repository hooks (for example to send signals to build bots such as Jenkins) and
even to monkey-patch certain parts of the Kallithea source code (for example
overwrite an entire function, change a global variable, ...).

To generate a skeleton extensions package, run::

    paster make-rcext my.ini

This will create an ``rcextensions`` package next to the specified ``ini`` file.
See the ``__init__.py`` file inside the generated ``rcextensions`` package
for more details.


Behavioral customization: code changes
--------------------------------------

As Kallithea is open-source software, you can make any changes you like directly
in the source code.

We encourage you to send generic improvements back to the
community so that Kallithea can become better. See :ref:`contributing` for more
details.