provide hook for dblog_filters

the demo module attached above (dblog_time_filters) addresses time filtering
not same but similar to what requests #251814: Add time based filter on watchdog overview page

this patch will facilitate implementations of any filter for log entries

also available for D6 #582672: dblog support filters through a hook (6.x)

rerolled with webchick's changes

I have already implemented a few log filters by means of custom modules taking advantage of this patch to dblog

having dblog to invoke hooks allows to provide filters (which might be enabled/disabled at will)
- filter by username (with autocompletion)
- filter by hostname
- filter by recent (configurable recent times)
- filter by aged (ditto)
- filber by date & time around +/- X time (not yet implemented)

the attached image shows two new filters taking advantage of hooks provided by this patch

Note: the UI changes are NOT part of this patch, this patch ONLY provides hooks for dblog module to look for the enabled filters

for those reviewing usability
screenshots are available showing what modules would be able to provide through these hooks on dblog
taking advantage of log_filter hook

@#10 please consider that this patch just "opens" the possibility to other modules to do this,
the actual filters are (by now) provided by modules out of dblog
therefore, how things gets laying out, or how it is styled was not addressed

if would be a "need" to have other filters, the first thing to do is to allow them with a hook, right?

do you think some of the filters in the screenshot should be in dblog from the beginning?
it can be done, but I recommend to keep "type" and "severity" being mandatory filters
and being available to get ride of any/every remaining filter (except for type & severity)

EDIT: typos

@#17 totally agree BUT

wait, please, that is exactly what I would like, yes, the filters them self got too late and would be better provided by dblog_filters as already did for D6

BUT instead of requiring a whole module to replace dblog's functionality

WHAT I'm requesting and the ONLY thing this patch is asking for are the hooks to be able to do that

in this comment 578488#comment-2064964 you can see that there are several modules involved
the ONLY one I want to get into core would be dblog_ext (the one providing the hook by means of duplicating dblog functions just to put some hooks in it)

the UI changes and the D6 modules might help deciding whether this would be a desirable issue to get into D7
BUT the actual proposed change is just: "provide hooks for filters support"

other modules will take advantage of those hooks to be the ones actually providing the filters

why this patch to dblog?

- check the attached image for illustration

- this patch provides 2 hooks: log_filters and log_filters_validate
(note that both hooks are prefixed with "log" instead of "dblog" since their are applicable to logs whether or not they are for "Recent log" report)

- with this two hooks implementing new optional filters to "Recent log" report would be very easy

- as an illustrative demostration there are two working modules attached (for D7)
-- one is dblog_filters which facilitates other modules to provide filters for "Recent log" report through regular log_filter hooks, since hooking into log_filters won't make autocompletion widgets available at core for instance, so this module provides the way
-- the other one is dblog_user_filter (with autocompletion)

how simple is dblog_user_filter?
as simple as the following code (is the whole module)

/**
 * Implementation of hook_log_filters_settings().
 */
function dblog_user_filter_log_filters_settings() {
  $settings['username'] = array(
    'title' => 'Username',
    'description'    => 'Filters by username with autocompletion.',
    //'page arguments' => array('dblog_user_filter_settings'),
    //'file'           => 'dblog_filters.user.admin.inc',
  );
  return $settings;
}

/**
 * Implementation of hook_log_filters_widget().
 */
function dblog_user_filter_log_filters_widget() {
  $filters['username'] = array(
    'title' => t('Username'),
    'where' => 'u.name = ?',
    'conjunction' => FALSE,
  );
  $filters['username']['widget'] = array(
    '#type' => 'textfield',
    '#autocomplete_path' => 'user/autocomplete',
    '#maxlength' => USERNAME_MAX_LENGTH,
    '#size' => 27, // fit the same with than <select>
  );
  return $filters;
}

PS: neither of the attached modules will work properly without this patch, since dblog_filters relies on it

for those reviewing usability
check why_dblog_patch.png for a visual explanation

this patch does NOT provides UI changes, ONLY provides new hooks
which in turn will allow other modules to enhance log filtering

this one needs to be re-rolled (I'll upload it soon)

two notes:
- current patch proposes a CSS selector change for dblog.css which has to be done for dblog-rtl.css as well
- currently dblog.admin.inc contains a bug at line 279, since variable $session does not exist any more, it should be $_SESSION['dblog_overview_filter'] (current patch used TRUE until now)

function dblog_filter_form($form) {
  $filters = dblog_filters();

  $form['filters'] = array(
    '#type' => 'fieldset',
    '#title' => t('Filter log messages'),
    '#theme' => 'dblog_filters',
    '#collapsible' => TRUE,
    '#collapsed' => empty($session), // <-- this variable was suppressed
  );

- new re-rolled patch ONLY differ in having dblog-rtl.css modified the same way dblog.css got modified
- dblog_user_filter module (uploaded @#21) launches some warnings (Invalid argument supplied for foreach() in theme_admin_page()) because it requires to be updated, BUT for testing purposes it works (just remember to visit admin/config/development/logging/filters to enable the filter after having dblog_user_filter module enabled)
- dblog.css & dblog-rtl.css are working (seeing through Firebug) but module's stylesheets are being overrided by theme's reset.css (with or without this patch)
- the above comment (@#24) about unexistent $session variable that should be $_SESSION['dblog_overview_filter'] is right for the existing bug in dblog module, but this patch initializes 'collapsed' => TRUE, and latter it expands filters' fieldset if at least one filter has a saved value (code is now commented)

    if (!empty($_SESSION['dblog_overview_filter'][$key])) {
      $form['filters']['status'][$key]['#default_value'] = $_SESSION['dblog_overview_filter'][$key];
      // expand filters fieldset if at least one filter has a saved value
      $form['filters']['#collapsed'] = FALSE;
    }

BTW: the above comment about module's stylesheet being overrided by theme's reset.css is an issue of theme Seven, those CSS can be successfully tested with Garland

EDIT: leaving a reference to the Seven issue regarding this CSS problem which is more notably when testing this patch but is present with or without this patch #674208: style.css dismisses module's css

Test bed refused windows line endings.

Ensure the patch only contains unix-style line endings.

this patch has nothing to do with FileFieldValidateTestCase which was the cause of the failing 2 tests and 14 exceptions (http://qa.drupal.org/pifr/test/23044)

lets wait until that get fixed to hit the bot again

I checked the logs around the failing test (http://qa.drupal.org/pifr/log/recent) and found other 2 tests (http://qa.drupal.org/pifr/test/23068 & http://qa.drupal.org/pifr/test/23268) which also failed due to upload problems plus exceptions (while the patches are unrelated with FileField).

But it doesn't seems to be usual, since other tests got through.
So... hitting the bot again...

int opened an issue for the bot failure #667264: [TESTING BROKEN] FileFieldValidateTestCase fails randomly

EDIT: the test of this issue already passed, leaving the above reference in case it comes up again

@NancyDru
it might..
test bot is green, I tested it, you tested it, anyone else?
did Dries and/or Bojhan test it?

comment #25 and more specifically #26 mention a CSS bug with Seven but not with Garland
the actual problem is within this patch:
dblog.css & dblog-rtl.css got their first CSS selector modified and I missed the selector prefix #dblog-filter-form which is causing Seven's style.css to achieve a narrower selector by means of div.form-item (which shouldn't happen with this patch)

Nevertheless, that's a minor flaw I will fix soon, the patch still needs review (which can be happily achieved with Garland)

@#40 NOT this patch's fault

-.form-item-type, .form-item-severity {
+.form-type-select {

the existing selectors are not working with Seven, which is getting a narrower selector with div.form-item, so currently dblog module has this error when using Seven and I shouldn't mix that fix within this patch

what would need consideration is using .form-type-select or .form-item
I used the most specific following what was already there for -type and -severity
but probably #dblog-filter-form .form-item would fit better

Note: for this to be appreciated in Seven (with or without this patch) the first selector in dblog.css & dblog-rtl.css has to be preceded by #dblog-filter-form (with a space before .form-*)

EDIT: typo fix

follow up:
the issues discovered while testing this patch (mentioned at #24, #25, #40, #41) got their separated issues (which if get fixed will require a re-roll of this one)
#674352: variable $session does not exist any more
#674354: CSS selectors get overridden by narrower selector at style.css when using Seven

rerolled same patch as #28
BUT with no CSS support for potential new filters (that would be another issue)

@#12 description wouldn't be a possible filter as long as watchdog saves pairs of 'message', $args for on-display-time translation (can't evaluate every translatable string on the fly for the current language to make a selection of them)
there are also the already translated logs which got pairs of t('message'), NULL that can be selected in the table, but they might be in several languages depending of the current language at the time they got into watchdog

I guarantee a new project dblog_filters taking care of username/hostname once this patch gets in (otherwise it would be the madness of reproducing dblog.admin.inc in a dblog_ext module, as done in util-6.x-3.x)
so it would be available for future core inclusion consideration (if it proves its worth)

I was reviewing this patch one more time, and found a couple of bothering unclearness
- now using 'multiple' (instead of odd 'conjunction')
- less modified code, aiming to be loyal to legacy code (works exactly the same though)

attached modules for testing this patch
please, use one at the time to avoid overloaded filters form
plus the username autocompletion is lacking some CSS for better fitness

also attached a CSS patch to make all select list properly float left
(which on the side solves #674354)
Note that the CSS patch was renamed as being for D6 to avoid test bot
since it is ONLY intended to be used for testing the patch of this issue with a more confortable CSS layout

Log time filters (dblog_time_filters):
- relies on hook_log_filters
- exposes recent/aged filters
- dependencies[] = dblog
- not relying on dblog_filters' API

Log filters (dblog_filters)
- relies on hook_log_filters
- provides an API easing custom filter implementations
- dependencies[] = dblog

Log hostname filter (dblog_host_filter)
- exposes hostname/IP filter
- dependencies[] = dblog_filters

Log user filter (dblog_user_filter)
- exposes username filter
- dependencies[] = dblog_filters

screenshots (modules with CSS patch at #49 for testing)
the actual patch of this issue is at #48

@Nahbyr#60
AFAIK this issue is unattended
with all due respect, Bojhan (@#10 & @#59) keeps wondering what this is about, despite my attempts to make it the most self-explanatory as possible

this is a request to introduce a harmless hook, in order to allow contrib to extend dblog's filters functionality
http://drupal.org/files/issues/why_dblog_patch.png