HowTo_LetterNewVariables

How LCO files are created to implement a complex corporate identity on the example of the University of Koblenz

In companies or at universities, there are often very specific ideas about how a letter should look. In the past, this was done exclusively with printed stationery. Nowadays, this is expected to be solved by word processing, so that letters sent as PDFs also have the desired appearance.

One of the strengths of the KOMA-Script letter class is that the stationery, i.e. the form, and also its individualization, i.e. the customizing of the content for individual persons, can be easily separated from the letter content. LCO files are used for both, typically the individual's LCO file directly loads the LCO file containing the general form.

The example here therefore not only shows how to specify a rather complex stationery with many new variables using an LCO for the form. It also shows how to create an LCO file for personal information and settings based on it in such a way that adjustments to the form are applied automatically. Only when defining new variables or deleting existing variables in the LCO file for the form, adjustments to the individual LCO file may be necessary.

Corporate Identity

The specifications for the form, i.e. the corporate identity, are based on those that once applied at the University of Koblenz. The example shown here therefore also originates from a suggestion by Uwe Jochum. In the meantime, the templates of the University of Koblenz are maintained independently. Employees of the university should therefore use the official template from the intranet.

A central element of the CI is a logo in the middle of the letterhead. To the right of this logo should be some information about the university, the institute or department and the person. Since the university is spread over several locations within the city, there is information about the accessibility by bus line in the foot. In addition, there are the bank details and a postal address for packages.

For the return address, there is a specification that the individual elements should be separated with a vertically centered dot instead of a comma. In addition, the font of the return address is fixed.

Some elements may occur more than once, for example, the name of the university and the city. The phone number, on the other hand, differs for individuals by only one user identifier. There are two slightly different numbers for faxes and for the telephone, but with a uniform user identifier. Besides the name of the university, a name for the institute or department is also needed. All this results in several new variables. Some of them have a default value. For example, the default “Zentralverwaltung” (this means: “Central Administration”) exists for the department. The switchboard number can also be used as the user identifier.

It is true that a logo exists as file 'unilogo.pdf'. However, if for some reason the file is not available, a simple substitute logo should be used. This can be easily implemented using \IfFileExists. For loading unilogo.pdf in the desired size of 3cm by 3cm the package graphicx is needed. However, it is allowed to load LCO files still in the document. To avoid that loading graphicx leads to an error message, the package is only loaded in the document preamble. Otherwise the LCO file relies on the user having loaded graphicx himself.

The signature should be set completely left-aligned, which can be easily solved using \raggedsignature.

All this can be wrapped in an LCO file as follows:

% uniexample.lco
% Copyright (c) Markus Kohm, 2021
% All rights reserved.
%
% https://sourceforge.net/p/koma-script/wiki-de/HowTo_LetterNewVariables
% https://sourceforge.net/p/koma-script/wiki-en/HowTo_LetterNewVariables

\ProvidesFile{uniexample.lco}[%
  2021/08/06 v0.1 
  LaTeX2e unsupported letter configuration option%
]

% Change of font of the back-address, because of
% corporated identity
\setkomafont{backaddress}{\rmfamily}

% Load package graphicx if possible
\if@atdocument\else\RequirePackage{graphicx}\fi

% Define some new variables and define some variable defaults:
\newkomavar{universityname}
\newkomavar{zipcode}
\newkomavar{department}% e.g. ``Institute of \LaTeX''
\newkomavar[\busroutename]{bus}% how to arrive with bus
\newkomavar{userphone}% the phone number part of the single user

\providecaptionname{british,UKenglish}{\busroutename}{bus route}
\providecaptionname{english,USenglish,american}{\busroutename}{bus line}
\providecaptionname{german,ngerman,swiss,nswiss,austrian,naustrian}{\busroutename}{Busverbindung}

% Set some variable, which are always the same
\setkomavar{universityname}{Universit\"at Exampulum}
\setkomavar{department}{Zentralverwaltung}% Default
\setkomavar{zipcode}{98765}
\setkomavar{place}{Urbaexampula}
\setkomavar{backaddress}{\usekomavar{universityname}\\
  \usekomavar{department}\\\usekomavar{zipcode} \usekomavar{place}}
\setkomavar{backaddressseparator}{ \textperiodcentered\ }
\setkomavar{fromlogo}{%
  \IfFileExists{signet.pdf}{%
    \includegraphics[width=3cmm,height=3cm]{unilogo.pdf}% use unilogo.pdf if available
  }{%
    \begingroup
      \setlength{\unitlength}{1mm}%
      \begin{picture}(30,30)
        \thicklines
        \put(0,0){\line(1,0){30}}%
        \put(30,0){\line(0,1){30}}%
        \put(30,30){\line(-1,0){30}}%
        \put(0,30){\line(0,-1){30}}%
        \put(0,0){\line(1,1){30}}%
        \put(0,30){\line(1,-1){30}}%
      \end{picture}
    \endgroup
  }%
}
\setkomavar{fromphone}{+428\,815\,77\,\usekomavar{userphone}}
\setkomavar{fromfax}{+428\,815\,78\,\usekomavar{userphone}}
\setkomavar{userphone}{00}% default: switchboard

% Define a new letter head
% (with tricky use of \makebox to center the logo):
\setkomavar{firsthead}{%
  \hspace*{\fill}%
  \usekomavar{fromlogo}%
  \makebox[0pt][l]{\quad
    \parbox[b]{\hsize}{\raggedright\small
      \textbf{\usekomavar{universityname}\\
        \usekomavar{department}\\
        \usekomavar{fromname}}\\
      \footnotesize{\usekomavar{fromaddress}%
        \if@phone\\
          \usekomavar*{fromphone}\usekomavar{fromphone}\fi
        \if@fax\\
          \usekomavar*{fromfax}\usekomavar{fromfax}\fi
        \if@email\\\usekomavar*{fromemail}\usekomavar{fromemail}\fi
        \if@www\\\usekomavar*{fromurl}\usekomavar{fromurl}\fi
      }}}%
  \hspace*{\fill}%
}

% Define a new letter foot
\setkomavar{firstfoot}{\scriptsize
  \begin{tabular}{@{}l@{}}
    \usekomavar*{bus}\\
    \usekomavar{bus}\\
  \end{tabular}%
  \hfill
  \begin{tabular}{@{}l@{}}
    Paketanschrift\\
    \usekomavar{fromaddress}\\
  \end{tabular}%
  \hfill
  \begin{tabular}{@{}l@{}}
    \usekomavar*{frombank}\\
    \usekomavar{frombank}\\
  \end{tabular}
}

\let\raggedsignature\raggedright
\endinput

By the way, not only a new variable bus was defined for the bus connection. The identifier was also defined language-dependently as \busroutename using \providecaptionname. Predefined are different terms for German, American English and British English. These are activated automatically by the language selection with babel.

Individualization

For individualization, another LCO file is created for each person. The individual settings are stored in this file. Since the file is based on uniexample.lco, it is loaded right at the beginning via \LoadLetterOption.

For example, for John Doe from the university library, this file may look like this:

% johndoe.lco
% Copyright (c) Markus Kohm, 2021
% All rights reserved.
%
% https://sourceforge.net/p/koma-script/wiki-de/HowTo_LetterNewVariables
% https://sourceforge.net/p/koma-script/wiki-en/HowTo_LetterNewVariables

\ProvidesFile{johndoe.lco}[%
  2021/08/06 v0.1
  LaTeX2e unsupported letter configuration option%
]

% We need LCO uniexample:
\LoadLetterOption{uniexample}

% Personalization
\KOMAoptions{fromphone,fromemail,symbolicnames}
\setkomavar{fromname}{Dr.\,John Doe}
\setkomavar{fromaddress}{Universit\"atsstra\ss e 10\\\usekomavar{zipcode} \usekomavar{place}}
\setkomavar{userphone}{12}
\setkomavar{fromemail}{john.doe@uniexample.invalid}
\setkomavar{signature}{Dr.\,John Doe\\(Fachreferent)}
\setkomavar{department}{Bibliothek}
\setkomavar{frombank}{Landeszentralbank Urbaexampula\\
  IBAN: DE01\,2345\,5678\,0123\,4567\,89}
\setkomavar{bus}{ab Hauptbahnhof: Linie 9A oder 9B\\
    ab Bahnhof Urbanea: Linie 11}

\endinput

Since this user considers faxes obsolete, he has enabled only phone number and e-mail for the letterhead via \KOMAoptions. He also prefers that phone and email are not written out there, but that pretty symbols are used for them.

As shown in the example of department and userphone, it is no problem to change variables already set in uniexample.lco. If the library had its own logo, you could also load it, for example via:

\setkomavar{logo}{\includegraphics[width=3cm,height=3cm]{biblogo}}

instead of the default logo.

Example Letter

A short example letter using the file above could be:

\documentclass{scrletter}% Note: The shown example also works with class scrlttr2.

\usepackage[UKenglish]{babel}
\usepackage{blindtext}

\LoadLetterOption{johndoe}
\setkomavar{yourmail}{30. Februar}
\setkomavar{yourref}{AcXb}
\setkomavar{customer}{007}
\setkomavar{invoice}{\usekomavar{customer}-002}
\setkomavar{date}{1. April 2021}

\begin{document}
\setkomavar{subject}{Example of the design of a stationery with several new variable}
\begin{letter}{Dr.\,Achim XBox\\Medienwissenschaft\\~\\im Haus}
  \opening{Dear Herr XBox,}
  \blindtext
  \closing{Regards}
\end{letter}
\end{document}

So you don't need to explicitly load both: uniexample.lco and johndoe.lco. Because johndoe.lco loads uniexample.lco itself explicitly loading of uniexample.lco would be possible but is redundant.

The result would be:

Of course, you can also set all information in a letter yourself via \setkomavar or change it again after loading johndoe.lco.

An overall example where uniexample.lco and johndoe.lco are created via filecontents environment can be found in the attachments as uniexample.tex.