% language=us runpath=texruns:manuals/workflows

\environment workflows-style

\startcomponent workflows-injectors

\startchapter[title={Injectors}]

When you have no control over the source but need to manually tweak some aspects
of the typesetting, like an occasional page break of column switch, you can use
the injector mechanism. This mechanism is part of list and register building but
can also be used elsewhere.

\startbuffer[one]
\startmixedcolumns[balance=yes]
  \dotestinjector{test}line 1 \par
  \dotestinjector{test}line 2 \par
  \dotestinjector{test}line 3 \par
  \dotestinjector{test}line 4 \par
  \dotestinjector{test}line 5
\stopmixedcolumns
\stopbuffer

\startbuffer[two]
\startmixedcolumns[balance=yes]
  \dotestinjector{test}line 1 \par
  \dotestinjector{test}line 2 \par
  \dotestinjector{test}line 3 \par
  \dotestinjector{test}line 4 \par
  \dotestinjector{test}line 5
\stopmixedcolumns
\stopbuffer

We have two buffers:

\typebuffer[one]

and

\typebuffer[two]

When typeset these come out as:

\blank \startpacked \bf \getbuffer[one] \stoppacked \blank

and

\blank \startpacked \bf \getbuffer[two] \stoppacked \blank

We can enable (and show) the injectors with:

\startbuffer
\doactivateinjector{test} \showinjector
\stopbuffer

\typebuffer \getbuffer

Now we get:

\blank \startpacked \bf \getbuffer[one] \stoppacked \blank

and

\blank \startpacked \bf \getbuffer[two] \stoppacked \blank

The small numbers are injector points. These will of course change when we add
more in|-|between. Let's add actions to some of the injection points:

\startbuffer
\setinjector[test][13][{\column}]
\setinjector[test][17][{\column}]
\stopbuffer

\typebuffer \getbuffer

As expected we now get column breaks:

\blank \startpacked \bf \getbuffer[one] \stoppacked \blank

and

\blank \startpacked \bf \getbuffer[two] \stoppacked \blank

The next example is one you can run for your own. The \type {\showinjector}
command is of course only enabled when the right injection points are to be
identified. Normally setting injectors happens as last resort. We use it in
automated \XML\ workflows where last minute control is needed.

\starttyping
\showinjector

\setinjector[register][3][\column]
\setinjector[list]    [2][{\blank[3*big]}]

\starttext
    \placelist[section][criterium=text]
    \blank[3*big]
    \placeregister[index][criterium=text]
    \page
    \startsection[title=Alpha] first  \index{first}  \stopsection
    \startsection[title=Beta]  second \index{second} \stopsection
    \startsection[title=Gamma] third  \index{third}  \stopsection
    \startsection[title=Delta] fourth \index{fourth} \stopsection
\stoptext
\stoptyping

\stopchapter

\stopcomponent

% Some day to be described (check Willis tests):
%
% \showinjector
%
% \xmlmapvalue{xml:injector}{column}{\setinjector[\AskedInjectorGroup][\AskedInjectorNumber][\column]}
% \xmlmapvalue{xml:injector}{page}  {\setinjector[\AskedInjectorGroup][\AskedInjectorNumber][\page]}
%
% \startxmlsetups xml:injector
%     \edef\AskedInjectorGroup {\xmlatt{#1}{group}}
%     \edef\AskedInjectorNumber{\xmlatt{#1}{number}}
%     \xmlvalue{xml:injector}{\xmlatt{#1}{type}}{}
% \stopxmlsetups
%
% \xmlfilter {#1} {/metadata/injectors/injector/command(xml:injector)}
%
% \xmlsetinjectors[\xmlattribute{#1}{/metadata/state}{version}]
%
% <?context-directive injector list 123 page ?>