projekt kivitendo

use List::MoreUtils qw(apply);

use SL::HelpSystem;

#

# Other class methods

#

sub override_help_contexts {

  my $class      = shift;

  my $controller = apply { s{.+:}{} } $class;

  SL::HelpSystem->override_help_contexts($controller, @_);

}

=head2 OTHER CLASS FUNCTIONS

=over 4

=item C<override_help_contexts %help_contexts>

Created overrides for the help context auto-detection by

L<SL::HelpSystem/context>. The keys given in the hash are action names

for which the help context is overridden.

The value can contain a slash in which case its used

verbatim. Otherwise value is taken to be an action name in the calling

controller and the controller's name will be prepended.

For example, in this example both targets will effectively be

C<BackgroundJob/edit>:

  package SL::Controller::BackgroundJob;

  use parent qw(SL::Controller::Base);

  __PACKAGE__->set_help_contexts(

    new    => 'edit',

    create => 'BackgroundJob/edit',

  );

=back

package SL::Controller::Help;

use strict;

use parent qw(SL::Controller::Base);

use SL::HelpSystem;

use SL::Helper::Flash;

use SL::Locale::String;

use Rose::Object::MakeMethods::Generic

(

  'scalar --get_set_init' => [ qw(context context_controller context_action) ],

);

#

# actions

#

sub action_show {

  my ($self) = @_;

  my @potential_pages;

  my $language = $::myconfig{countrycode};

  $language    = undef if ($language // '') eq 'de';

  if ($self->context_controller) {

    if ($language) {

      push @potential_pages, { language => $language, category => $self->context_controller, topic => $self->context_action } if $self->context_action;

      push @potential_pages, { language => $language, category => $self->context_controller, topic => '_index' };

    }

    push @potential_pages, { language => 'de', category => $self->context_controller, topic => $self->context_action } if $self->context_action;

    push @potential_pages, { language => 'de', category => $self->context_controller, topic => '_index' };

  }

  push @potential_pages, { language => $language, topic => '_index' } if $language;

  push @potential_pages, { language => 'de',      topic => '_index' };

  my $page = $::request->help_system->page_available(@potential_pages);

  return $::form->error(t8("No help page to show was found.")) if !$page;

  $::request->layout(SL::Layout::Dispatcher->new(style => 'none'));

  $::request->layout->use_stylesheet('help.css');

  $self->render(

    'help/show',

    title   => t8('kivitendo help'),

    content => $::request->help_system->convert_page_to_html(%$page),

  );

}

#

# helpers

#

sub init_context            { $::form->{context} // ''           }

sub init_context_controller { (split m{/}, $_[0]->context, 2)[0] }

sub init_context_action     { (split m{/}, $_[0]->context, 2)[1] }

1;

package SL::HelpSystem;

use strict;

use parent qw(Rose::Object);

use List::Util qw(first);

use SL::System::Process;

use Rose::Object::MakeMethods::Generic (

  'scalar --get_set_init' => [ qw(context base_path driver) ],

);

my %custom_help_contexts;

sub init_base_path { SL::System::Process::exe_dir() . '/templates/webpages/help' }

sub init_driver {

  require SL::HelpSystem::MultiMarkdown;

  return SL::HelpSystem::MultiMarkdown->new;

}

sub init_context {

  my ($controller, $action) = $::request ? ($::request->controller, $::request->action) : ();

  return undef if !$controller;

  my $override = ($custom_help_contexts{$controller} // {})->{$action};

  return $override               if $override && ($override =~ m{/});

  return "$controller/$override" if $override;

  return "$controller/$action"   if $action;

  return $controller;

}

sub page_available {

  my ($self, @pages) = @_;

  return first { -f $self->file_name_for_page(%$_) } @pages;

}

sub file_name_for_page {

  my ($self, %page) = @_;

  my $sub_path = join '/', grep { ($_ // '') ne '' } @page{ qw(language category topic) };

  return $self->base_path . '/content/' . $sub_path . '.' . $self->driver->file_name_extension;

}

sub convert_page_to_html {

  my ($self, %page) = @_;

  my $file_name = $self->file_name_for_page(%page);

  return -f $file_name ? $self->driver->convert_to_html($file_name) : undef;

}

sub sanitize {

  my ($self, $name) = @_;

  $name //= '';

  $name   =~ s{[^a-z0-9_-]+}{}gi;

  return $name;

}

sub override_help_contexts {

  my ($class, $controller, %help_contexts) = @_;

  $custom_help_contexts{$controller} = \%help_contexts;

}

1;

__END__

=pod

=encoding utf8

=head1 NAME

SL::HelpSystem - Help system helper functions

=head1 SYNOPSIS

  my $help_system = SL::HelpSystem->new;

  my $page = $help_system->page_available('de/ic/add');

  if ($page) {

    $self->render(

      'help/show',

      title   => t8('kivitendo help'),

      content => $help_system->convert_page_to_html($page),

    );

  }

=head1 FUNCTIONS

=over 4

=item C<base_path>

Returns the base path where all the help pages are stored.

=item C<context>

This gets or sets the help context. The help context is used by the

layout when displaying a link to the help system.

If a controller does not set a help context then it defaults to

C<controller/action> as returned by the two functions with the same

name in the L<SL::Request> object.

=item C<convert_page_to_html %page>

Converts a markup help page to HTML and returns the converted

HTML. The C<%page> parameter must be a hash suitable for

L</file_name_for_page>.

=item C<driver>

Gets or sets the driver to use. The default driver supports

MultiMarkdown via L<SL::HelpSystem::MultiMarkdown>.

=item C<file_name_for_page %page>

Returns the file name for a help page. Note that the file may or may

not exist.

The C<%page> must be a hash with the following keys: C<language>,

C<category> and C<topic>. Their values are sanitized with the

L</sanitize> function and concatenated in exactly this order to form

the actual file name. Elements that aren't set are skipped.

The C<category> will usually be a controller name and the C<topic>

will usually be an action for that controller.

=item C<page_available @pages>

Returns the first page for which a file name as given by

L</file_name_for_page> exists. C<@pages> must be an array of hash refs

suitable for L</file_name_for_page>.

=item C<sanitize $name>

Page name components may only consist of the following characters: the

characters C<a-z> and C<A-Z>, digits C<0-9> and the special characters

C<_> and C<->.

This function removes all other characters from C<$name> and returns

the cleaned version.

=back

=head1 BUGS

Nothing here yet.

=head1 AUTHOR

Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>

=cut

package SL::HelpSystem::MultiMarkdown;

use strict;

use parent qw(Rose::Object);

use Encode ();

use File::Slurp ();

use Text::MultiMarkdown;

use Rose::Object::MakeMethods::Generic (

  'scalar --get_set_init' => [ qw(multimarkdown) ],

);

sub init_multimarkdown {

  return Text::MultiMarkdown->new(

    empty_element_suffix => '>',

    tab_width            => 4,

  );

}

sub file_name_extension { "mmd" }

sub convert_to_html {

  my ($self, $file_name) = @_;

  my $markup = Encode::decode('utf-8', scalar(File::Slurp::slurp($file_name)));

  return $self->multimarkdown->markdown($markup);

}

1;

  { name => "Text::MultiMarkdown",                 url => "https://metacpan.org/pod/Template::Plugin::MultiMarkdown", debian => 'libtext-multimarkdown-perl' },

  # The help system is currently disabled by default as most of its

  # content is still missing. It would be a disservice to users if it

  # were enabled in such a state. For developers and documenters

  # working on the documentation the feature must be turned on. Once

  # enough documentation has been written the feature will be enabled

  # unconditionally.

  push @options, (help_context => $::request->help_system->context) if $::lx_office_conf{devel}->{enable_help_system};

use SL::HelpSystem;

  'scalar --get_set_init' => [ qw(cgi layout presenter is_ajax type help_system) ],

sub init_help_system {

  return SL::HelpSystem->new;

}

# The help system is currently disabled by default as most of its

# content is still missing. It would be a disservice to users if it

# were enabled in such a state. For developers and documenters working

# on the documentation the feature must be turned on. Once enough

# documentation has been written the feature will be enabled

# unconditionally.

enable_help_system = 0

.kivitendo-help pre {

  background-color: #eee;

  overflow: auto;

}

.kivitendo-help thead th {

	padding: 0.2em;

	background-color: #EBEBEB;

	color: #006400;

	font-weight: bolder;

	text-align: left;

	border-style: none;

}

.kivitendo-help tbody tr:nth-child(odd) {

	background-color: #FFFF99;

	color: black;

	vertical-align: top;

}

.kivitendo-help tbody tr:nth-child(even) {

	background-color: #FFFFFF;

	color: black;

	vertical-align: top;

}

.kivitendo-help pre {

  background-color: #eee;

  overflow: auto;

}

  'Help'                        => 'Hilfe',

  'No help page to show was found.' => 'Es wurde keine anzuzeigende Hilfeseite gefunden.',

  'Open kivitendo\'s help system in a new window' => 'Öffnet kivitendo\'s Hilfesystem in einem neuen Fenster',

  'kivitendo help'              => 'kivitendo-Hilfe',

# kivitendo-Hilfe

Willkommen bei der [kivitendo](http://www.kivitendo.org/)-Hilfe. Dies ist die Startseite.

## Externe Hilfequellen

Es gibt mehrere externe Hilfequellen, die Sie kontaktieren können:

* [das Forum](https://forum.kivitendo.de:32443/)

* [den Bugtracker](http://redmine.kivitendo-premium.de/projects/forum/issues)

* [die Mailinglisten](http://www.kivitendo.org/community/mailinglisten.html)

# Hauptüberschrift

Dieser Abschnitt enthält Informationen zum Anlegen neuer oder Bearbeiten bestehender Artikel in den Stammdaten.

Doppelte Zeilenumbrüche sollten einen neuen Absatz einleiten.

Einzelne Zeilenumbrüche im Quelltext

sollten auch in der Ausgabe

einen Zeilenumbruch erzeugen.

## Kleinere Überschrift

Eine Leerzeile nach einer Überschrift sollte nicht nötig sein.

Eine Leerzeile vor einer Überschrift sollte nicht nötig sein.

## Auch eine Überschrift

Bauen wir eine Aufzählungsliste:

* Punkt eins

* Punkt zwei

* Noch ein Punkt

Und nun eine mit Nummerierung:

1. Weil ich das toll finde.

2. Weil ich immer Recht habe.

3. Mehr Begründungen werden selbstverständlich dann auch nicht benötigt.

Jezt folgt ein Block, der besonders hervorgehoben werden soll:

==Achtung!

Dies ist die öffentliche Bekanntmachung, dass kivitendo toll ist!==

Jut. Nun dann. Was brauchen wir noch? Richtig, eine Tabelle!

| Film/Serie | Zitat |

|--------|--------|

| Battlestar Galactica |  So say we all! |

| Dirty Dancing | Ich habe eine Wassermelone getragen. |

| Ghostbusters | Er schleimte mich voll. |

Textauszeichnung[^1] ist auch wichtig. Reden wir über *kursiv* oder **fett** oder gar `typesetter`? Wer weiß das schon so genau!

Externe Links wie z.B. zur [kivitendo-Homepage](http://www.kivitendo.org/) sind auch wichtig.

Codeblöcke sind interessant. Diese werden eingerückt:

    package Sparta;

    sub new {

      say "This is ", $_[0], "!";

    }

Das geht aber auch anders:

```

package Sparta;

sub new {

  say "This is ", $_[0], "!";

}

```

Alrighty.

Ein Bild sagt mehr als ein besoffener Hund.

![Ein Bild, ein Bild](image/kivitendo.png)

[^1]: Stay away from da Voodoo, mon!

[%- USE HTML -%]

<html>

 <head>

  <title>[% HTML.escape(title) %]</title>

 </head>

 <body class="kivitendo-help">

  [% content %]

 </body>

</html>

[%- USE T8 %][%- USE LxERP -%][%- USE HTML -%]

[%- IF help_context %]

    [<a href="controller.pl?action=Help/show&context=[% HTML.url(help_context) %]" target="_kivitendo_help", title="[% LxERP.t8("Open kivitendo's help system in a new window") %]">[% LxERP.t8("Help") %]</a>]

[%- END %]