How to read "the meanings" of efx templates (in order to build a custom viewer)

[fabiodisconzi]

I am trying to develop a notice viewer using .php.
The road is not simple and I am following several ways to get to the target (without success).
The last idea comes from looking at files in: view-templates/16.efx

Question zero: any suggest in order to understand how they are written? Thanks.

First question: are all published notices following the structure of that templates? In other words, for a viewer application are that templates a consistent "scheletron"? Do they provide a guidance about "what info, which data, etc" a particular subtype of notice would have?

If yes, they could be a draft for starting to develop a "php viewer". Or not?
Parsing all rows of template will provide to user all notice information, right?
Information will come from the notice xml_file, Xpaht and making iterative loops through nodes.
I think it's a road worth trying... Or please stop me now :-)

MAIN QUESTION: how to "read" that templates?

Some ideas:

1. Rows which starts with numbers refers to "chapter / heders" of notice, right?
2. it is very useful the comment after "//" separator
3. I suppose the | symbol stands for "OR" operator, right?
4. what is the meaning of "#" symbol?
5. what is the meaning of "$" symbol?
6. what is the meaning of "0" and "1" at the beginning of some indented rows?

Anyone interested in discover more about the template files?

Best Regards,
Fabio

[pdonohoe]

Dear Fabio,

Thanks for an interesting question!

Please see also the sample Java application for visualising eForms notices https://github.com/OP-TED/eforms-notice-viewer, especially the Freemarker / XSLT templates at https://github.com/OP-TED/eforms-notice-viewer/blob/develop/src/main/resources/templates/xsl_markup/output_file.ftl

The templates are written in a domain-specific language called "EFX". The grammar for this language is in the SDK github repository: https://github.com/OP-TED/eForms-SDK/blob/main/efx-grammar/Efx.g4 and https://github.com/OP-TED/eForms-SDK/blob/main/efx-grammar/EfxLexer.g4. The EFX templates are interpreted using the tool in https://github.com/OP-TED/efx-toolkit-java and converted into XSLT. This XSLT is applied to the notice XML to get the HTML. This is used for all the viewers.

The EFX template lines are stored and edited in a database. The template lines in the database have a single sequence order, which is used in all the .efx files. So the EFX lines, and hence the display of lines in the HTML will always be in the same order. And each line is always displayed in the same way, the only differences coming from the information in the notice XML.

The database also holds tables defining which template lines are used for which eForms subtypes. These tables are edited manually, and the rules come from the Regulation Annex Excel table. These tables are combined to create the .efx files included in the eForms SDK. There is no single .efx files that is a "template" for the others, as there is no single eForms subtype that uses every defined Field/BT. That said, file 16.efx is a good one to start with, for Contract Notice forms. I also typically use 29.efx for Contract Award Notices, and 6.efx for Prior Information Notices.

You are right, the XSLT generated from these EFX lines iterate through the nodes, in a hierarchical way. The template lines all share the same basic structure:

• indent - this determines both the indent applied to the output HTML, and also the hierarchy of the lines and the XML context in which the line is applied. Each line with indent X is a "descendant" of, and inherits the context of the first preceding line with indent X - 1.

• Optional number: these do also indicate "header" lines

  • If the line does not have any descendant lines (following lines with a greater indent), then no numbering is displayed
  • If the line number is "0", then no numbering is displayed.
  • If the line number is not "0", then it is appended to the numbering of "ancestor" lines

• Context declaration block - mandatory. This part uses { and } to enclose the context declaration. This determines whether the line will appear at all, and is applied to only the results of the ancestor lines. Starting with the context of the "parent" line, it is evaluated against the XML. Only if it evaluates to "true" is the line (and any descendant lines) displayed. It uses the IDs of Fields and Nodes; these are all listed in the fields/fields.json file.

• One or more of the following:

  • Label blocks. These use #{ } to enclose the label code. This is evaluated to generate the ID of a label. The symbol "|" is used to separate the parts of the ID. Then this is used in combination with the user-selected display language to select the label text from the XML files in the "translations" folder. So "#{field|name|BT-137-Lot}" when the user selects "English" as the viewer language, selects that entry in translations/field_en.xml, which is "Lot technical ID".

  • Expression blocks. These use ${ } to enclose the expression code. These are evaluated to locate the text content of Fields in the XML. Rules are also applied to their display depending on the type of data (the "type" property of the Field in fields/fields.json). If the "type" property is "text-multilingual", only one language is displayed; the language chosen is the first available one of: the user-selected language, BT-702(a)-notice : "Notice Official Language", BT-702(b)-notice : "Notice Official Language".

    The code within the context declaration blocks and expression blocks use similar syntax to XPath; [] are used to apply predicates, and the "concat()", "if", "for X in Y return Z" and "some X in Y satisfies Z" are exactly the same as XPath.

  • Text. This is outside any {} symbols, and is simply rendered. For example the text ":" is usually displayed after the first label block.

• Comment. The first occurrence of "//" terminates the evaluation of the line, and anything after is a comment. I have tried to describe the use or meaning of each line in this comment.

Please let us know how you get on with your project.

Best regards,
Paul

[fabiodisconzi]

Many thanks for the answer. I am trying to develop a procedural list of functions in order to display a notice using the .efx template as "framework".

Taking into account:

xpression blocks. These use ${ } to enclose the expression code. These are evaluated to locate the text content of Fields in the XML. Rules are also applied to their display depending on the type of data (the "type" property of the Field in fields/fields.json). If the "type" property is "text-multilingual", only one language is displayed; the language chosen is the first available one of: the user-selected language, BT-702(a)-notice : "Notice Official Language", BT-702(b)-notice : "Notice Official Language".
The code within the context declaration blocks and expression blocks use similar syntax to XPath; [] are used to apply predicates, and the "concat()", "if", "for X in Y return Z" and "some X in Y satisfies Z" are exactly the same as XPath.

For instance, how to set-up a function for this line:
{ND-ContractingParty} #{field|name|BT-500-Organization-Company}: ${for text:$orgid in OPT-300-Procedure-Buyer, text:$orgname in BT-500-Organization-Company[OPT-200-Organization-Company == $orgid] return $orgname} // Official name

I am in trouble understanding:
${for text:$orgid in OPT-300-Procedure-Buyer, text:$orgname in BT-500-Organization-Company[OPT-200-Organization-Company == $orgid] return $orgname}

What does it tells us to do?
Maybe: make a for cycle in all organization company that are reported in the .xml of the notice but return the value only when OPT-200-Organization-Company == $orgid

I am stuck in this rules because with my code the "custom viewer" give me 3 organizations and not only one.
What am I missing?

What topic should I study more to better understand how a template .efx works?

Your support is really appreciated!
Fabio

[fabiodisconzi]

Another step, a little step, further.
Just to tell you my advancements and to write down some notes that could be useful for other developers.

I take into account the 16.efx file (the template).
Focus on this row, row number 7:
{BT-10-Procedure-Buyer} #{field|name|BT-10-Procedure-Buyer}: #value // Activity of the contracting authority

The info that would be useful to get the Absolute Xpath of info is: BT-10-Procedure-Buyer.
I use this identifier as "link" with field.json file.
Is it a good idea?

Ok, in the field list this identifier bring to the following Xpath:

and this Xpath applied for example to notice 219158-2024 (https://ted.europa.eu/en/notice/-/detail/219158-2024)
returns me:
gen-pub

That is correct.
But I do not feel confident at 100% that my procedure is 100% correct.
For instace on field.json there are many data related to same identifier. I need to better understad how it works... maybe should I consider also the parentNodeId

Best Regards,
Fabio