.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "OpenGuides::CGI 3pm"
.TH OpenGuides::CGI 3pm "2021-01-30" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
OpenGuides::CGI \- An OpenGuides helper for CGI\-related things.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Does \s-1CGI\s0 stuff for OpenGuides.  Distributed and installed as part of
the OpenGuides project, not intended for independent installation.
This documentation is probably only useful to OpenGuides developers.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Saving preferences in a cookie:
.PP
.Vb 4
\&  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
\&  );
.Ve
.PP
Tracking visits to Recent Changes:
.PP
.Vb 4
\&  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,
\&  );
.Ve
.SH "METHODS"
.IX Header "METHODS"
.IP "\fBextract_node_param\fR" 4
.IX Item "extract_node_param"
.Vb 4
\&    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 );
.Ve
.Sp
Returns the title, id, or keywords parameter from the \s-1URL.\s0  Normally
this will be something like \*(L"British_Museum\*(R", i.e. with underscores
instead of spaces.  However if the \s-1URL\s0 does contain spaces (encoded as
\&\f(CW%20\fR or +), the return value will be e.g. \*(L"British Museum\*(R" instead.
.Sp
Croaks unless a Wiki::Toolkit object is supplied as \f(CW\*(C`wiki\*(C'\fR and a
\&\s-1CGI\s0 object is supplied as \f(CW\*(C`cgi_obj\*(C'\fR.
.IP "\fBextract_node_name\fR" 4
.IX Item "extract_node_name"
.Vb 4
\&    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 );
.Ve
.Sp
Returns the name of the node the user wishes to display/manipulate, as
we expect it to be stored in the database.  Normally this will be
something like \*(L"British Museum\*(R", i.e. with spaces in.  Croaks unless a
Wiki::Toolkit object is supplied as \f(CW\*(C`wiki\*(C'\fR and a \s-1CGI\s0 object is
supplied as \f(CW\*(C`cgi_obj\*(C'\fR.
.IP "\fBescape\fR" 4
.IX Item "escape"
.Vb 1
\&    my $param = OpenGuides::CGI\->escape( "foo?!!??!?!" );
.Ve
.Sp
Does exactly the same as \s-1CGI\s0\->escape (that is, encodes a string so it can
safely be included in a \s-1URL\s0), but doesn't escape commas (because it's not
necessary, and looks ugly).
.IP "\fBcheck_spaces_redirect\fR" 4
.IX Item "check_spaces_redirect"
.Vb 3
\&    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 );
.Ve
.Sp
If the user seems to have typed a \s-1URL\s0 with spaces in the node param
instead of underscores, this method will return the \s-1URL\s0 with the
underscores put in.  Otherwise, it returns false.
.IP "\fBmake_prefs_cookie\fR" 4
.IX Item "make_prefs_cookie"
.Vb 10
\&  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
\&  );
.Ve
.Sp
Croaks unless an OpenGuides::Config object is supplied as \f(CW\*(C`config\*(C'\fR.
Acceptable values for \f(CW\*(C`cookie_expires\*(C'\fR are \f(CW\*(C`never\*(C'\fR, \f(CW\*(C`month\*(C'\fR,
\&\f(CW\*(C`year\*(C'\fR; anything else will default to \f(CW\*(C`month\*(C'\fR.
.IP "\fBget_prefs_from_cookie\fR" 4
.IX Item "get_prefs_from_cookie"
.Vb 4
\&  my %prefs = OpenGuides::CGI\->get_prefs_from_cookie(
\&      config => $config,
\&      cookies => \e@cookies
\&  );
.Ve
.Sp
Croaks unless an OpenGuides::Config object is supplied as \f(CW\*(C`config\*(C'\fR.
Returns default values for any parameter not specified in cookie.
.Sp
If \f(CW\*(C`cookies\*(C'\fR is provided, and includes a preferences cookie, this overrides
any preferences cookie submitted by the browser.
.IP "\fBmake_recent_changes_cookie\fR" 4
.IX Item "make_recent_changes_cookie"
.Vb 3
\&  my $cookie = OpenGuides::CGI\->make_recent_changes_cookie(
\&      config => $config,
\&  );
.Ve
.Sp
Makes a cookie that stores the time now as the time of the latest
visit to Recent Changes.  Or, if \f(CW\*(C`clear_cookie\*(C'\fR is specified and
true, makes a cookie with an expiration date in the past:
.Sp
.Vb 4
\&  my $cookie = OpenGuides::CGI\->make_recent_changes_cookie(
\&      config       => $config,
\&      clear_cookie => 1,
\&  );
.Ve
.IP "\fBget_last_recent_changes_visit_from_cookie\fR" 4
.IX Item "get_last_recent_changes_visit_from_cookie"
.Vb 3
\&  my %prefs = OpenGuides::CGI\->get_last_recent_changes_visit_from_cookie(
\&      config => $config
\&  );
.Ve
.Sp
Croaks unless an OpenGuides::Config object is supplied as \f(CW\*(C`config\*(C'\fR.
Returns the time (as seconds since epoch) of the user's last visit to
Recent Changes.
.IP "\fBmake_index_form_dropdowns\fR" 4
.IX Item "make_index_form_dropdowns"
.Vb 8
\&    my @dropdowns = OpenGuides::CGI\->make_index_form_dropdowns (
\&        guide    => $guide,
\&        selected => [
\&                      { type => "category", value => "pubs" },
\&                      { type => "locale", value => "holborn" },
\&                    ],
\&    );
\&    %tt_vars = ( %tt_vars, dropdowns => \e@dropdowns );
\&
\&    # In the template
\&    [% FOREACH dropdown = dropdowns %]
\&      [% dropdown.type.ucfirst | html %]:
\&      [% dropdown.html %]
\&      <br />
\&    [% END %]
.Ve
.Sp
Makes \s-1HTML\s0 dropdown selects suitable for passing to an indexing template.
.Sp
The \f(CW\*(C`selected\*(C'\fR argument is optional; if supplied, 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.
.SH "AUTHOR"
.IX Header "AUTHOR"
The OpenGuides Project (openguides\-dev@lists.openguides.org)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
.Vb 1
\&     Copyright (C) 2003\-2013 The OpenGuides Project.  All Rights Reserved.
.Ve
.PP
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.