OpenGuides::CGI(3pm)

📦
version 0.84 · 3 versions
, in debian bookworm, ubuntu jammy, ubuntu noble

💖 OpenGuides::CGI(3pm) 💖

okay bestie, listen — this is OpenGuides::CGI, a little helper module from the User Contributed Perl Documentation corner of the universe. It's the CGI-glue bestie of the OpenGuides project, and it's here to do the fiddly web-plumbing bits so you don't have to. 🫶

✨ NAME ✨

OpenGuides::CGI — an OpenGuides helper for CGI-related things. that's it, that's the whole job description, and honestly? iconic. 👑

🌸 DESCRIPTION 🌸

It does the CGI stuff for OpenGuides. fr fr. It ships and installs as part of the whole OpenGuides project, and it is not meant to be installed all by itself — it's a package deal, no solo debuts here. 💅

Real talk though: this documentation is probably only useful to OpenGuides developers. If you're just vibing and trying to run a wiki, this is not your page. If you're in the code, welcome, you're the main character now. 🎀

🦋 SYNOPSIS 🦋

Saving preferences in a cookie:

  use OpenGuides::CGI;
  use OpenGuides::Config;
  use OpenGuides::Template;
  use OpenGuides::Utils;

  my $config = OpenGuides::Config->new( file => "wiki.conf" );

  my $cookie = OpenGuides::CGI->make_prefs_cookie(
      config                     => $config,
      username                   => "Kake",
      include_geocache_link      => 1,
      preview_above_edit_box     => 1,
      latlong_traditional        => 1,
      omit_help_links            => 1,
      show_minor_edits_in_rc     => 1,
      default_edit_type          => "tidying",
      cookie_expires             => "never",
      track_recent_changes_views => 1,
      display_google_maps        => 1,
      is_admin                   => 1
  );

  my $wiki = OpenGuides::Utils->make_wiki_object( config => $config );
  print OpenGuides::Template->output( wiki     => $wiki,
                                      config   => $config,
                                      template => "preferences.tt",
                                      cookies  => $cookie
  );

  # and to retrive prefs later:
  my %prefs = OpenGuides::CGI->get_prefs_from_cookie(
      config => $config
  );

Tracking visits to Recent Changes:

  use OpenGuides::CGI;
  use OpenGuides::Config;
  use OpenGuides::Template;
  use OpenGuides::Utils;

  my $config = OpenGuides::Config->new( file => "wiki.conf" );

  my $cookie = OpenGuides::CGI->make_recent_changes_cookie(
      config => $config,
  );

👑 METHODS 👑

bestie, we got a whole roster. every single one, no skipping, let's go. 🌈

🍓 extract_node_param

  my $config_file = $ENV{OPENGUIDES_CONFIG_FILE} || "wiki.conf";
  my $config = OpenGuides::Config->new( file => $config_file );
  my $guide = OpenGuides->new( config => $config );
  my $wiki = $guide->wiki;

  my $q = CGI->new;

  my $node_param = OpenGuides::CGI->extract_node_param(
                      wiki => $wiki, cgi_obj => $q );

It hands you back the title, id, or keywords parameter from the URL. Normally that looks like "British_Museum" — yeah, underscores instead of spaces, that's just how we do. BUT if the URL actually has spaces in it (encoded as %20 or +), then you get "British Museum" instead. plot twist, love that for us. ✨

💀 Heads up: it croaks unless you give it a Wiki::Toolkit object as wiki and a CGI object as cgi_obj. No object, no vibe, no mercy.

🧚 extract_node_name

  my $config_file = $ENV{OPENGUIDES_CONFIG_FILE} || "wiki.conf";
  my $config = OpenGuides::Config->new( file => $config_file );
  my $guide = OpenGuides->new( config => $config );
  my $wiki = $guide->wiki;

  my $q = CGI->new;

  my $node_name = OpenGuides::CGI->extract_node_name(
                      wiki => $wiki, cgi_obj => $q );

Returns the name of the node the user wants to display/manipulate, exactly as we expect it to live in the database. So normally it's like "British Museum" — with actual spaces this time. Croaks unless a Wiki::Toolkit object comes in as wiki and a CGI object comes in as cgi_obj. same energy, same rule. 🫠

🌸 escape

  my $param = OpenGuides::CGI->escape( "foo?!!??!?!" );

Does literally exactly the same thing as CGI->escape — like, encodes a string so it's safe to drop into a URL — except it doesn't escape commas. why? because escaping commas isn't necessary and it looks ugly. aesthetic choice, and she's right. 💅

🌈 check_spaces_redirect

  my $config_file = $ENV{OPENGUIDES_CONFIG_FILE} || "wiki.conf";
  my $config = OpenGuides::Config->new( file => $config_file );
  my $guide = OpenGuides->new( config => $config );

  my $q = CGI->new;

  my $url = OpenGuides::CGI->check_spaces_redirect(
                               wiki => $wiki, cgi_obj => $q );

If the user looks like they typed a URL with actual spaces in the node param instead of underscores, this method returns the URL with the underscores put in. Otherwise it returns false. no spaces allowed in the node param, we're fixing it for you, you're welcome. 🎀

  my $cookie = OpenGuides::CGI->make_prefs_cookie(
      config                     => $config,
      username                   => "Kake",
      include_geocache_link      => 1,
      preview_above_edit_box     => 1,
      latlong_traditional        => 1,
      omit_help_links            => 1,
      show_minor_edits_in_rc     => 1,
      default_edit_type          => "tidying",
      cookie_expires             => "never",
      track_recent_changes_views => 1,
      display_google_maps        => 1,
      is_admin                   => 1
  );

Croaks unless an OpenGuides::Config object is supplied as config. 🙈

The acceptable values for cookie_expires are "never", "month", and "year". Anything else? defaults to "month". that's the rule, no cap. ⭐

  my %prefs = OpenGuides::CGI->get_prefs_from_cookie(
      config => $config,
      cookies => \@cookies
  );

Croaks unless an OpenGuides::Config object is supplied as config. Returns default values for any parameter not specified in cookie. 💖

If cookies is provided, and it includes a preferences cookie, then it overrides any preferences cookie that the browser submitted. yes bestie, your explicit cookies argument wins. periodt. 👑

  my $cookie = OpenGuides::CGI->make_recent_changes_cookie(
      config => $config,
  );

Makes a cookie that stores the time now as the time of the latest visit to Recent Changes. or, if clear_cookie is specified and true, it makes a cookie with an expiration date in the past — goodbye cookie, you're history: 🕰️

  my $cookie = OpenGuides::CGI->make_recent_changes_cookie(
      config       => $config,
      clear_cookie => 1,
  );
  my %prefs = OpenGuides::CGI->get_last_recent_changes_visit_from_cookie(
      config => $config
  );

Croaks unless an OpenGuides::Config object is supplied as config. Returns the time (as seconds since epoch) of the user's last visit to Recent Changes. that's the timestamp, bestie, raw and unfiltered. ⏱️

🫶 make_index_form_dropdowns

  my @dropdowns = OpenGuides::CGI->make_index_form_dropdowns (
      guide    => $guide,
      selected => [
                    { type => "category", value => "pubs" },
                    { type => "locale", value => "holborn" },
                  ],
  );
  %tt_vars = ( %tt_vars, dropdowns => \@dropdowns );

  # In the template
  [% FOREACH dropdown = dropdowns %]
    [% dropdown.type.ucfirst | html %]:
    [% dropdown.html %]
    <br />
  [% END %]

Makes HTML dropdown selects that are suitable for passing to an indexing template. cute little select menus, love that for the template. 🎁

The selected argument is optional; if you supply it, it gives default values for the dropdowns. At least one category and one locale dropdown will be returned; if no defaults are given for either, then they'll default to everything/everywhere. go big or go home. 🌍

💖 AUTHOR 💖

The OpenGuides Project (openguides-dev@lists.openguides.org)

     Copyright (C) 2003-2013 The OpenGuides Project.  All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 🫶

okay that's the whole page bestie, you ate, no crumbs left ✨💅

This one's from the Perl v5.32.0 era, dated 2021-01-30 — shoutout to the OpenGuides::CGI(3pm) manual page for being the blueprint. mwah. 💜🎀🦋

📦 where this page comes from