3,899
edits
Changes
Created page with "Documentation for \useblocks"
<cd:commandgroup name="useblocks" xmlns:cd="http://wiki.contextgarden.net/commanddoc/20200807">
<cd:shortdesc>The command <tt>\useblocks</tt> is used to typeset blocks
</cd:shortdesc>
<cd:variants>
<cd:command category="structure" file="strc-blk.mkiv" interfacedate="2020-04-24T11:54" interfacefile="i-block.xml" level="document" name="useblocks" variantnumber="1">
<cd:arguments>
<cd:keywords list="yes" ordinal="1">
<cd:keywordsdoc></cd:keywordsdoc>
<cd:constant type="cd:name"></cd:constant>
</cd:keywords>
<cd:keywords list="yes" optional="yes" ordinal="2">
<cd:keywordsdoc></cd:keywordsdoc>
<cd:constant type="cd:name"></cd:constant>
</cd:keywords>
<cd:assignments list="yes" optional="yes" ordinal="3">
<cd:assignmentsdoc></cd:assignmentsdoc>
<cd:parameter name="criterium">
<cd:paramdoc></cd:paramdoc>
<cd:constant default="yes" type="text"></cd:constant>
<cd:constant type="cd:section"></cd:constant>
</cd:parameter>
</cd:assignments>
</cd:arguments>
</cd:command>
</cd:variants>
<cd:description>Typesets all the requested blocks defined in the document, in the order in which they were defined. An optional second argument can be used to print only blocks with certain tags.
</cd:description>
<cd:examples><cd:example title=""><context source="yes" text="This gives:">
\setuppapersize[A7]
\defineblock[myquestion]
\defineblock[myanswer]
% We don't want to display blocks when we define them.
\hideblocks[myquestion,myanswer]
\starttext
\beginmyquestion[first]
First question, defined at the start
\endmyquestion
\beginmyanswer[first]
First answer
\endmyanswer
\subsection{My questions and answers, original interleaving}
\useblocks[myquestion,myanswer]
\subsection{Only the first answer}
\useblocks[myanswer][first]
\beginmyquestion
Second block, defined at the end
\endmyquestion
\beginmyanswer
Second answer, also defined at the end
\endmyanswer
\subsection{You can't select by tag only}
\useblocks[first] % produces nothing
\useblocks[][first] % produces nothing
\stoptext
</context>
</cd:example><cd:example title="Test if a block is empty or not">In some cases, one may want use the collected blocks, e. g., at the end of a chapter, preceded (of course) with a section header. However, some chapters may not have had blocks, so that an empty section would appear. In this case, {{cmd|doifelseblocksempty}} it comes in handy to test if a block is empty or not (will work from some upload in Aug 2021 onwards):
<context source="yes">
\setuppapersize[A7]
\defineblock[testa]
\defineblock[testb]
\starttext
\begintestb
Test B was a great!
\endtestb
\doifelseblocksempty {testa}{}{} {\section{Test A}} {Nothing to show here} % {name}{tag}{criterium}
\doifelseblocksempty {testb}{}{} {\section{Test B}} {Nothing to show here} % {name}{tag}{criterium}
\stoptext
</context></cd:example></cd:examples>
<cd:notes></cd:notes>
<cd:seealso>
<cd:source file="strc-blk.mkiv" originator="system"></cd:source>
<cd:wikipage originator="system" page="Category:Structure"></cd:wikipage>
<cd:commandref name="defineblock">to define a new kind of block.</cd:commandref>
<cd:commandref name="setupblock">to set up block style.</cd:commandref>
<cd:commandref name="keepblocks">to start displaying blocks where they are defined.</cd:commandref></cd:seealso>
</cd:commandgroup>
<cd:shortdesc>The command <tt>\useblocks</tt> is used to typeset blocks
</cd:shortdesc>
<cd:variants>
<cd:command category="structure" file="strc-blk.mkiv" interfacedate="2020-04-24T11:54" interfacefile="i-block.xml" level="document" name="useblocks" variantnumber="1">
<cd:arguments>
<cd:keywords list="yes" ordinal="1">
<cd:keywordsdoc></cd:keywordsdoc>
<cd:constant type="cd:name"></cd:constant>
</cd:keywords>
<cd:keywords list="yes" optional="yes" ordinal="2">
<cd:keywordsdoc></cd:keywordsdoc>
<cd:constant type="cd:name"></cd:constant>
</cd:keywords>
<cd:assignments list="yes" optional="yes" ordinal="3">
<cd:assignmentsdoc></cd:assignmentsdoc>
<cd:parameter name="criterium">
<cd:paramdoc></cd:paramdoc>
<cd:constant default="yes" type="text"></cd:constant>
<cd:constant type="cd:section"></cd:constant>
</cd:parameter>
</cd:assignments>
</cd:arguments>
</cd:command>
</cd:variants>
<cd:description>Typesets all the requested blocks defined in the document, in the order in which they were defined. An optional second argument can be used to print only blocks with certain tags.
</cd:description>
<cd:examples><cd:example title=""><context source="yes" text="This gives:">
\setuppapersize[A7]
\defineblock[myquestion]
\defineblock[myanswer]
% We don't want to display blocks when we define them.
\hideblocks[myquestion,myanswer]
\starttext
\beginmyquestion[first]
First question, defined at the start
\endmyquestion
\beginmyanswer[first]
First answer
\endmyanswer
\subsection{My questions and answers, original interleaving}
\useblocks[myquestion,myanswer]
\subsection{Only the first answer}
\useblocks[myanswer][first]
\beginmyquestion
Second block, defined at the end
\endmyquestion
\beginmyanswer
Second answer, also defined at the end
\endmyanswer
\subsection{You can't select by tag only}
\useblocks[first] % produces nothing
\useblocks[][first] % produces nothing
\stoptext
</context>
</cd:example><cd:example title="Test if a block is empty or not">In some cases, one may want use the collected blocks, e. g., at the end of a chapter, preceded (of course) with a section header. However, some chapters may not have had blocks, so that an empty section would appear. In this case, {{cmd|doifelseblocksempty}} it comes in handy to test if a block is empty or not (will work from some upload in Aug 2021 onwards):
<context source="yes">
\setuppapersize[A7]
\defineblock[testa]
\defineblock[testb]
\starttext
\begintestb
Test B was a great!
\endtestb
\doifelseblocksempty {testa}{}{} {\section{Test A}} {Nothing to show here} % {name}{tag}{criterium}
\doifelseblocksempty {testb}{}{} {\section{Test B}} {Nothing to show here} % {name}{tag}{criterium}
\stoptext
</context></cd:example></cd:examples>
<cd:notes></cd:notes>
<cd:seealso>
<cd:source file="strc-blk.mkiv" originator="system"></cd:source>
<cd:wikipage originator="system" page="Category:Structure"></cd:wikipage>
<cd:commandref name="defineblock">to define a new kind of block.</cd:commandref>
<cd:commandref name="setupblock">to set up block style.</cd:commandref>
<cd:commandref name="keepblocks">to start displaying blocks where they are defined.</cd:commandref></cd:seealso>
</cd:commandgroup>