Layout

Layout#

NAME#

Kernel::Output::HTML::Layout - all generic html functions

DESCRIPTION#

All generic html functions. E. g. to get options fields, template processing, …

PUBLIC INTERFACE#

new()#

create a new object. Do not use it directly, instead use:

use Kernel::System::ObjectManager;
local $Kernel::OM = Kernel::System::ObjectManager->new(
    'Kernel::Output::HTML::Layout' => {
        Lang    => 'de',
    },
);
my $LayoutObject = $Kernel::OM->Get('Kernel::Output::HTML::Layout');

From the web installer, a special Option InstallerOnly is passed to indicate that a database connection is not yet available.

use Kernel::System::ObjectManager;
local $Kernel::OM = Kernel::System::ObjectManager->new(
    'Kernel::Output::HTML::Layout' => {
        InstallerOnly => 1,
    },
);
my $LayoutObject = $Kernel::OM->Get('Kernel::Output::HTML::Layout');

Block()#

call a block and pass data to it (optional) to generate the block’s output.

$LayoutObject->Block(
    Name => 'Row',
    Data => {
        Time => ...,
    },
);

JSONEncode()#

Encode perl data structure to JSON string

my $JSON = $LayoutObject->JSONEncode(
    Data        => $Data,
    NoQuotes    => 0|1, # optional: no double quotes at the start and the end of JSON string
);

Redirect()#

return html for browser to redirect

my $HTML = $LayoutObject->Redirect(
    OP => "Action=AdminUserGroup;Subaction=User;ID=$UserID",
);

my $HTML = $LayoutObject->Redirect(
    ExtURL => "http://some.example.com/",
);

During login action, Login = 1> should be passed to Redirect(), which indicates that if the browser has cookie support, it is OK for the session cookie to be not yet set.

Notify()#

create notify lines

infos, the text will be translated

my $Output = $LayoutObject->Notify(
    Priority => 'Warning',
    Info => 'Some Info Message',
);

data with link, the text will be translated

my $Output = $LayoutObject->Notify(
    Priority  => 'Warning',
    Data      => 'Template content',
    Link      => 'http://example.com/',
    LinkClass => 'some_CSS_class',              # optional
);

errors, the text will be translated

my $Output = $LayoutObject->Notify(
    Priority => 'Error',
    Info => 'Some Error Message',
);

errors from log backend, if no error exists, a '' will be returned

my $Output = $LayoutObject->Notify(
    Priority => 'Error',
);

NotifyNonUpdatedTickets()#

Adds notification about tickets which are not updated.

my $Output = $LayoutObject->NotifyNonUpdatedTickets();

Ascii2Html()#

convert ASCII to html string

my $HTML = $LayoutObject->Ascii2Html(
    Text            => 'Some <> Test <font color="red">Test</font>',
    Max             => 20,       # max 20 chars flowed by [..]
    VMax            => 15,       # first 15 lines
    NewLine         => 0,        # move \r to \n
    HTMLResultMode  => 0,        # replace " " with C<&nbsp;>
    StripEmptyLines => 0,
    Type            => 'Normal', # JSText or Normal text
    LinkFeature     => 0,        # do some URL detections
);

also string ref is possible

my $HTMLStringRef = $LayoutObject->Ascii2Html(
    Text => \$String,
);

LinkQuote()#

detect links in text

my $HTMLWithLinks = $LayoutObject->LinkQuote(
    Text => $HTMLWithOutLinks,
);

also string ref is possible

my $HTMLWithLinksRef = $LayoutObject->LinkQuote(
    Text => \$HTMLWithOutLinksRef,
);

HTMLLinkQuote()#

detect links in HTML code

my $HTMLWithLinks = $LayoutObject->HTMLLinkQuote(
    String => $HTMLString,
);

also string ref is possible

my $HTMLWithLinksRef = $LayoutObject->HTMLLinkQuote(
    String => \$HTMLString,
);

LinkEncode()#

perform URL encoding on query string parameter names or values.

my $ParamValueEncoded = $LayoutObject->LinkEncode($ParamValue);

Don’t encode entire URLs, because this will make them invalid (?, & and ; will be encoded as well). Only pass one parameter name or value at a time.

BuildSelection()#

build a HTML option element based on given data

my $HTML = $LayoutObject->BuildSelection(
    Data            => $ArrayRef,        # use $HashRef, $ArrayRef or $ArrayHashRef (see below)
    Name            => 'TheName',        # name of element
    ID              => 'HTMLID',         # (optional) the HTML ID for this element, if not provided, the name will be used as ID as well
    Multiple        => 0,                # (optional) default 0 (0|1)
    Size            => 1,                # (optional) default 1 element size
    Class           => 'class',          # (optional) a css class, include 'Modernize' to activate InputFields
    Disabled        => 0,                # (optional) default 0 (0|1) disable the element
    AutoComplete    => 'off',            # (optional)
    OnChange        => 'javascript',     # (optional)
    OnClick         => 'javascript',     # (optional)

    SelectedID     => 1,                 # (optional) use integer or arrayref (unable to use with ArrayHashRef)
    SelectedID     => [1, 5, 3],         # (optional) use integer or arrayref (unable to use with ArrayHashRef)
    SelectedValue  => 'test',            # (optional) use string or arrayref (unable to use with ArrayHashRef)
    SelectedValue  => ['test', 'test1'], # (optional) use string or arrayref (unable to use with ArrayHashRef)

    Sort           => 'NumericValue',    # (optional) (AlphanumericValue|NumericValue|AlphanumericKey|NumericKey|TreeView|IndividualKey|IndividualValue) unable to use with ArrayHashRef
    SortIndividual => ['sec', 'min']     # (optional) only sort is set to IndividualKey or IndividualValue
    SortReverse    => 0,                 # (optional) reverse the list

    Translation    => 1,                 # (optional) default 1 (0|1) translate value
    PossibleNone   => 0,                 # (optional) default 0 (0|1) add a leading empty selection
    TreeView       => 0,                 # (optional) default 0 (0|1)
    DisabledBranch => 'Branch',          # (optional) disable all elements of this branch (use string or arrayref)
    Max            => 100,               # (optional) default 100 max size of the shown value
    HTMLQuote      => 0,                 # (optional) default 1 (0|1) disable html quote
    Title          => 'C<Tooltip> Text',    # (optional) string will be shown as c<Tooltip> on c<mouseover>
    OptionTitle    => 1,                 # (optional) default 0 (0|1) show title attribute (the option value) on every option element

    Filters => {                         # (optional) filter data, used by InputFields
        LastOwners => {                  # filter id
            Name   => 'Last owners',     # name of the filter
            Values => {                  # filtered data structure
                Key1 => 'Value1',
                Key2 => 'Value2',
                Key3 => 'Value3',
            },
            Active => 1,                 # (optional) default 0 (0|1) make this filter immediately active
        },
        InvolvedAgents => {
            Name   => 'Involved in this ticket',
            Values => \%HashWithData,
        },
    },
    ExpandFilters  => 1,                 # (optional) default 0 (0|1) expand filters list by default

    ValidateDateAfter  => '2016-01-01',  # (optional) validate that date is after supplied value
    ValidateDateBefore => '2016-01-01',  # (optional) validate that date is before supplied value
);

my $HashRef = {
    Key1 => 'Value1',
    Key2 => 'Value2',
    Key3 => 'Value3',
};

my $ArrayRef = [
    'KeyValue1',
    'KeyValue2',
    'KeyValue3',
    'KeyValue4',
];

my $ArrayHashRef = [
    {
        Key   => '1',
        Value => 'Value1',
    },
    {
        Key      => '2',
        Value    => 'Value1::Subvalue1',
        Selected => 1,
    },
    {
        Key   => '3',
        Value => 'Value1::Subvalue2',
    },
    {
        Key      => '4',
        Value    => 'Value2',
        Disabled => 1,
    }
];

Permission()#

check if access to a frontend module exists

my $Access = $LayoutObject->Permission(
    Action => 'AdminCustomerUser',
    Type   => 'rw', # ro|rw possible
);

Attachment()#

returns browser output to display/download a attachment

$HTML = $LayoutObject->Attachment(
    Type             => 'inline',          # optional, default: attachment, possible: inline|attachment
    Filename         => 'FileName.png',    # optional
    AdditionalHeader => $AdditionalHeader, # optional
    ContentType      => 'image/png',
    Content          => $Content,
    Sandbox          => 1,                 # optional, default 0; use content security policy to prohibit external
                                           #   scripts, flash etc.
);

or for AJAX html snippets

$HTML = $LayoutObject->Attachment(
    Type        => 'inline',        # optional, default: attachment, possible: inline|attachment
    Filename    => 'FileName.html', # optional
    ContentType => 'text/html',
    Charset     => 'utf-8',         # optional
    Content     => $Content,
    NoCache     => 1,               # optional
);

BuildDateSelection()#

build the HTML code to represent a date selection based on the given data. Depending on the SysConfig settings the controls to set the date could be multiple select or input fields

my $HTML = $LayoutObject->BuildDateSelection(
    Prefix           => 'some prefix',        # optional, (needed to specify other parameters)
    <Prefix>Year     => 2015,                 # optional, defaults to current year, used to set the initial value
    <Prefix>Month    => 6,                    # optional, defaults to current month, used to set the initial value
    <Prefix>Day      => 9,                    # optional, defaults to current day, used to set the initial value
    <Prefix>Hour     => 12,                   # optional, defaults to current hour, used to set the initial value
    <Prefix>Minute   => 26,                   # optional, defaults to current minute, used to set the initial value
    <Prefix>Second   => 59,                   # optional, defaults to current second, used to set the initial value
    <Prefix>Optional => 1,                    # optional, default 0, when active a checkbox is included to specify
                                              #   if the values should be saved or not
    <Prefix>Used     => 1,                    # optional, default 0, used to set the initial state of the checkbox
                                              #   mentioned above
    <Prefix>Required => 1,                    # optional, default 0 (Deprecated)
    <prefix>Class    => 'some class',         # optional, specify an additional class to the HTML elements
    Area     => 'some area',                  # optional, default 'Agent' (Deprecated)
    DiffTime => 123,                          # optional, default 0, used to set the initial time influencing the
                                              #   current time (in seconds)
    OverrideTimeZone => 1,                    # optional (1 or 0), when active the time is not translated to the user
                                              #   time zone
    YearPeriodFuture => 3,                    # optional, used to define the number of years in future to be display
                                              #   in the year select
    YearPeriodPast   => 2,                    # optional, used to define the number of years in past to be display
                                              #   in the year select
    YearDiff         => 0,                    # optional. used to define the number of years to be displayed
                                              #   in the year select (alternatively to YearPeriodFuture and YearPeriodPast)
    ValidateDateInFuture     => 1,            # optional (1 or 0), when active sets an special class to validate
                                              #   that the date set in the controls to be in the future
    ValidateDateNotInFuture  => 1,            # optional (1 or 0), when active sets an special class to validate
                                              #   that the date set in the controls not to be in the future
    ValidateDateAfterPrefix  => 'Start',      # optional (Prefix), when defined sets a special class to validate
                                              #   that the date set in the controls comes after the date with Prefix
    ValidateDateAfterValue   => '2016-01-01', # optional (Date), when defined sets a special data parameter to validate
                                              #   that the date set in the controls comes after the supplied date
    ValidateDateBeforePrefix => 'End',        # optional (Prefix), when defined sets a special class to validate
                                              #   that the date set in the controls comes before the date with Prefix
    ValidateDateBeforeValue  => '2016-01-01', # optional (Date), when defined sets a special data parameter to validate
                                              #   that the date set in the controls comes before the supplied date
    Calendar => 2,                            # optional, used to define the SysConfig calendar on which the Datepicker
                                              #   will be based on to show the vacation days and the start week day
    Format   => 'DateInputFormat',            # optional, or 'DateInputFormatLong', used to define if only date or
                                              #   date/time components should be shown (DateInputFormatLong shows date/time)
    Validate => 1,                            # optional (1 or 0), defines if the date selection should be validated on
                                              #   client side with JS
    Disabled => 1,                            # optional (1 or 0), when active select and checkbox controls gets the
                                              #   disabled attribute and input fields gets the read only attribute
);

HumanReadableDataSize()#

Produces human readable data size.

my $SizeStr = $LayoutObject->HumanReadableDataSize(
    Size => 123,  # size in bytes
);

Returns

$SizeStr = '123 B';         # example with decimal point: 123.4 MB

Ascii2RichText()#

converts text to rich text

my $HTMLString = $LayoutObject->Ascii2RichText(
    String => $TextString,
);

RichText2Ascii()#

converts text to rich text

my $TextString = $LayoutObject->RichText2Ascii(
    String => $HTMLString,
);

RichTextDocumentComplete()#

  1. add html, body, … tags to be a valid html document

  2. replace links of inline content e. g. images to <img src=”cid:xxxx” />

$HTMLBody = $LayoutObject->RichTextDocumentComplete(
    String => $HTMLBody,
);

_RichTextReplaceLinkOfInlineContent()#

replace links of inline content e. g. images

$HTMLBodyStringRef = $LayoutObject->_RichTextReplaceLinkOfInlineContent(
    String => $HTMLBodyStringRef,
);

RichTextDocumentServe()#

Serve a rich text (HTML) document for local view inside of an C<iframe> in correct charset and with correct links for inline documents.

By default, all inline/active content (such as C<script>, C<object>, C<applet> or C<embed> tags) will be stripped. If there are external images, they will be stripped too, but a message will be shown allowing the user to reload the page showing the external images.

my %HTMLFile = $LayoutObject->RichTextDocumentServe(
    Data => {
        Content     => $HTMLBodyRef,
        ContentType => 'text/html; charset="iso-8859-1"',
    },
    URL               => 'AgentTicketAttachment;Subaction=HTMLView;TicketID=123;ArticleID=123;FileID=',
    Attachments       => \%AttachmentListOfInlineAttachments,

    LoadInlineContent => 0,     # Serve the document including all inline content. WARNING: This might be dangerous.

    LoadExternalImages => 0,    # Load external images? If this is 0, a message will be included if
                                # external images were found and removed.
);

RichTextDocumentCleanup()#

please see L<Kernel::System::HTML::Layout::DocumentCleanup()>

_BuildSelectionOptionRefCreate()#

create the option hash

my $OptionRef = $LayoutObject->_BuildSelectionOptionRefCreate(
    %Param,
);

my $OptionRef = {
    Sort         => 'numeric',
    PossibleNone => 0,
    Max          => 100,
}

_BuildSelectionAttributeRefCreate()#

create the attribute hash

my $AttributeRef = $LayoutObject->_BuildSelectionAttributeRefCreate(
    %Param,
);

my $AttributeRef = {
    name     => 'TheName',
    multiple => undef,
    size     => 5,
}

_BuildSelectionDataRefCreate()#

create the data hash

my $DataRef = $LayoutObject->_BuildSelectionDataRefCreate(
    Data => $ArrayRef,              # use $HashRef, $ArrayRef or $ArrayHashRef
    AttributeRef => $AttributeRef,
    OptionRef => $OptionRef,
);

my $DataRef  = [
    {
        Key => 11,
        Value => 'Text',
    },
    {
        Key => 'abc',
        Value => '&nbsp;&nbsp;Text',
        Selected => 1,
    },
];

_BuildSelectionOutput()#

create the html string

my $HTMLString = $LayoutObject->_BuildSelectionOutput(
    AttributeRef       => $AttributeRef,
    DataRef            => $DataRef,
    TreeView           => 0,              # optional, see BuildSelection()
    FiltersRef         => \@Filters,      # optional, see BuildSelection()
    FilterActive       => $FilterActive,  # optional, see BuildSelection()
    ExpandFilters      => 1,              # optional, see BuildSelection()
    ValidateDateAfter  => '2016-01-01',   # optional, see BuildSelection()
    ValidateDateBefore => '2016-01-01',   # optional, see BuildSelection()
);

my $AttributeRef = {
    name => 'TheName',
    multiple => undef,
    size => 5,
}

my $DataRef  = [
    {
        Key => 11,
        Value => 'Text',
        Disabled => 1,
    },
    {
        Key => 'abc',
        Value => '&nbsp;&nbsp;Text',
        Selected => 1,
    },
];

_RemoveScriptTags()#

This function will remove the surrounding <script> tags of a piece of JavaScript code, if they are present, and return the result.

my $CodeContent = $LayoutObject->_RemoveScriptTags(Code => $SomeCode);

WrapPlainText()#

This sub has two main functionalities: 1. Check every line and make sure that “n” is the ending of the line. 2. If the line does _not_ start with “>” (e.g. not cited text) wrap it after the number of “MaxCharacters” (e.g. if MaxCharacters is “80” wrap after 80 characters). Do this _just_ if the line, that should be wrapped, contains space characters at which the line can be wrapped.

If you need more info to understand what it does, take a look at the UnitTest WrapPlainText.t to see use cases there.

my $WrappedPlainText = $LayoutObject->WrapPlainText(

PlainText => “Some Plain text that is longer than the amount stored in MaxCharacters”, MaxCharacters => 80,

);

SetRichTextParameters()#

set properties for rich text editor and send them to JS via AddJSData()

$LayoutObject->SetRichTextParameters(

Data => %Param,

);

CustomerSetRichTextParameters()#

set properties for customer rich text editor and send them to JS via AddJSData()

$LayoutObject->CustomerSetRichTextParameters(

Data => %Param,

);

UserInitialsGet()#

Get initials from a full name of a user.

my $UserInitials = $LayoutObject->UserInitialsGet(
    Fullname => 'John Doe',
);

Returns string of exactly two uppercase characters that represent user initials:

$UserInitials = 'JD';

Please note that this function will return ‘O’ if invalid name (without any word characters) was supplied.

_BuildLastViewsOutput()#

Outputs links to the last views of the (customer) user in the avatar area, tool bar or menu bar.

my $LastViewsHTML = $LayoutObject->_BuildLastViewsOutput(
    Interface => 'Agent',       # or Customer
    Position  => 'ToolBar',     # or MenuBar or Avatar, for customer interface only MenuBar is possible.
);

_GetShortcutIconsForInterface()#

Returns the paths to the shortcut icons of the given interface.

my %ShortcutConfig = $LayoutObject->_GetShortcutIconsForInterface(
    Interface => 'Agent',    # or Customer
);
Contents