Filtre admin

src/admin.rs           ModelAdmin::new().list(|l| l.filter([Lang, SectionId]))
      │
démarrage              vérification : aucune colonne secrète
      │
requête GET            /admin/doc_page?filter_lang=fr&filter_lang=en&page=1
      │
handler liste          1. valeurs distinctes de chaque colonne filtrable (barre latérale)
                       2. conditions des filtres choisis + liste + total
      │
template Tera          groupes repliables, liens qui ajoutent ou retirent une valeur

// src/admin.rs
fn doc_page() -> ModelAdmin<doc_page::Entity> {
    use doc_page::Column::*;
    ModelAdmin::new().list(|l| {
        l.display([Title, Lang, SectionId])
            .filter([Lang, SectionId])
            .filter_size(10)              // valeurs par groupe avant les flèches de pagination
    })
}

// runique/src/admin/builder/list.rs (extrait)
pub fn filter(mut self, cols: impl IntoIterator<Item = E::Column>) -> Self {
    self.filter = cols.into_iter().collect();
    self
}

// runique/src/admin/builder/admin_builder.rs (extrait)
for secret in E::SECRET {
    let name = secret.as_str();
    for list in self
        .list
        .lists_using(name)
        .into_iter()
        .chain(self.form.lists_using(name))
    {
        errors.push(format!(
            "{list}: `{name}` is a secret column, never shown, searched, filtered, sorted or written by the admin"
        ));
    }
}

// runique/src/admin/builder/list.rs (extrait)
/// The values a filter offers for `col`: the distinct ones of the rows in
/// `scope`, as text (how `resolve_filters` compares them), sorted, NULL
/// left out, `page` of `size` of them. One more than `size` is read: its
/// presence says a next page exists, without counting the values.
pub(crate) fn filter_values(
    backend: DbBackend,
    scope: Condition,
    col: E::Column,
    page: u64,
    size: u64,
) -> Select<E> {
    let cast = Alias::new(text_cast_type_of(backend));
    // The databases take a signed 64-bit offset: a huge page from the URL
    // stays in range instead of failing the query.
    let offset = std::cmp::Ord::min(
        page.saturating_sub(1).saturating_mul(size),
        i64::MAX.unsigned_abs(),
    );
    E::find()
        .filter(scope)
        .filter(col.is_not_null())
        .select_only()
        .column_as(Expr::col((E::default(), col)).cast_as(cast), FILTER_VALUE)
        .distinct()
        .order_by_asc(Expr::col(Alias::new(FILTER_VALUE)))
        .offset(offset)
        .limit(size.saturating_add(1))
}

Le SQL produit ressemble à :

SELECT DISTINCT CAST("lang" AS TEXT) AS filter_value
FROM "doc_page"
WHERE <périmètre autorisé> AND "lang" IS NOT NULL
ORDER BY filter_value ASC
LIMIT 11 OFFSET 0

let mut valeurs: Vec<String> = /* résultat de filter_values, size + 1 au plus */ vec![];
let size = 10;
let page_suivante = valeurs.len() as u64 > size;
valeurs.truncate(size as usize);       // n'afficher que la page demandée

Compter toutes les valeurs distinctes coûterait une requête de plus et un parcours complet. Lire size + 1 lignes suffit pour savoir s'il faut afficher la flèche « suivant ».

let page: u64 = 0;                         // une page 0 venue de l'URL
let offset = page.saturating_sub(1)        // 0 au lieu d'un dépassement (0 - 1)
    .saturating_mul(10);                   // reste dans les bornes d'un u64

Toute valeur numérique venue d'une URL peut être 0, énorme ou absurde : saturating_* la garde dans les bornes sans paniquer (cours variables-et-fonctions, section 5).

?filter_lang=fr&filter_lang=en&filter_section_id=3

Une valeur est un paramètre filter_<colonne>=<valeur>. Plusieurs valeurs d'une même colonne se répètent.

// runique/src/admin/builder/list.rs (extrait)
pub(crate) fn resolve_filters(
    &self,
    backend: DbBackend,
    filters: &[(String, String)],
) -> Option<Condition> {
    let cast = Alias::new(text_cast_type_of(backend));
    let mut cond = Condition::all();                         // ET entre les colonnes
    for col in &self.filter {                                // seulement les colonnes DÉCLARÉES
        let one_of = filters
            .iter()
            .filter(|(name, _)| name == col.as_str())
            .fold(Condition::any(), |any, (_, value)| {      // OU entre les valeurs d'une colonne
                any.add(
                    Expr::col((E::default(), *col))
                        .cast_as(cast.clone())
                        .eq(value.as_str()),
                )
            });
        if !one_of.is_empty() {
            cond = cond.add(one_of);
        }
    }
    (!cond.is_empty()).then_some(cond)
}

Pour l'URL de la section 5.1 :

WHERE (CAST(lang AS TEXT) = 'fr' OR CAST(lang AS TEXT) = 'en')
  AND (CAST(section_id AS TEXT) = '3')

use sea_orm::Condition;

// Avec une boucle et une variable mutable
fn une_colonne_v1(valeurs: &[&str]) -> Condition {
    let mut any = Condition::any();
    for v in valeurs {
        any = any.add(doc_page::Column::Lang.eq(*v));
    }
    any
}

// Avec fold (forme de Runique)
fn une_colonne_v2(valeurs: &[&str]) -> Condition {
    valeurs.iter().fold(Condition::any(), |any, v| any.add(doc_page::Column::Lang.eq(*v)))
}

// Avec IN : une seule expression
fn une_colonne_v3(valeurs: &[&str]) -> Condition {
    Condition::all().add(doc_page::Column::Lang.is_in(valeurs.iter().copied()))
}

IN serait plus court, mais Runique compare en texte pour traiter tous les types de colonne de la même façon : la forme avec cast_as et OR garde un seul code pour un booléen, un entier ou une énumération.

// runique/src/admin/router/context.rs (extrait)
pub struct FilterOption {
    pub value: String,
    /// Whether the list is filtered on this value.
    pub active: bool,
    /// `?…` of the list with this value turned on or off.
    pub qs: String,
}

impl FilterOption {
    pub(crate) fn new(params: &[(String, String)], column: &str, value: String) -> Self {
        let name = format!("filter_{column}");
        let is_it = |k: &str, v: &str| k == name && v == value;
        let active = params.iter().any(|(k, v)| is_it(k, v));
        let qs = encoded_query(
            params
                .iter()
                .filter(|(k, v)| k != "page" && !is_it(k, v))      // tous les paramètres sauf la page et cette valeur
                .map(|(k, v)| (k.as_str(), v.as_str()))
                .chain((!active).then_some((name.as_str(), value.as_str())))   // + cette valeur si elle était inactive
                .chain(std::iter::once(("page", "1"))),             // + retour à la première page
        );
        Self { value, active, qs }
    }
}

{# runique/templates/admin/blocks/list/filters.html (extrait) #}
{% for filter_entry in resource.display.list_filter %}
  {% set col = filter_entry[0] %}
  {% set label = filter_entry[1] %}
  {% set values = filter_values[col] %}
  {% if values and values | length > 0 %}
  <div class="admin-filter__group" data-filter-col="{{ col }}">
    <button class="admin-filter__group-title" type="button" aria-expanded="true">{{ label }}</button>
    <div class="admin-filter__group-body">
      {% if filter_clear[col] %}
      <a href="{{ filter_clear[col] }}" hx-get="{{ filter_clear[col] }}"
        hx-target="#list-content" hx-swap="outerHTML" hx-push-url="true"
        class="admin-filter__option admin-filter__option--clear">{{ admin_list_filters_clear }}</a>
      {% endif %}
      {# Each link turns its value on or off, the others kept. #}
      {% for option in values %}
        <a href="{{ option.qs }}" hx-get="{{ option.qs }}"
          hx-target="#list-content" hx-swap="outerHTML" hx-push-url="true"
          class="admin-filter__option {% if option.active %}admin-filter__option--active{% endif %}">
          {{ option.value | replace(from="_", to=" ") }}
        </a>
      {% endfor %}
      {% set pager = filter_pagers[col] %}
      {% if pager.prev_qs or pager.next_qs %}
        {% include "admin/blocks/list/pager.html" %}
      {% endif %}
    </div>
  </div>
  {% endif %}
{% endfor %}

// runique/static/js/admin/admin-list.js (extrait)
const KEY = 'runique_fg_' + RESOURCE + '_' + col;
const stored = sessionStorage.getItem(KEY);
// Replié par défaut sauf préférence explicite (sessionStorage)

clé : runique_fg_doc_page_lang
      '1'               → ouvert
      autre ou absent   → replié