Early Bird Registration for DrupalCon Portland 2024 is open! Register by 23:59 PST on 31 March 2024, to get $100 off your ticket.
Since I haven't seen it explicitly discussed anywhere else in this project, and I'm running up against several different variations in terminology, what can we agree is the best way to title and document template_preprocess functions?
I'll use theme('item_list')
as an example.
a.
/**
* Preprocess variables for an item list.
*/
b.
/**
* Preprocess variables for theme('item_list').
*/
...?
Comments
Comment #1
steveoliver CreditAttribution: steveoliver commentedc.
Comment #2
steveoliver CreditAttribution: steveoliver commentedd.
prefer C. so far.
Comment #3
jenlamptonI also like C :)
Comment #4
artofeclipse CreditAttribution: artofeclipse commentedC looks good for me :)
Comment #5
vlad.dancerExample from user.admin.inc
Comment #6
star-szrIn #1898460-4: taxonomy.module - Convert PHPTemplate templates to Twig we seem to have come up with a new option…
e.
Any objections? Or do we think plural "templates" makes sense when taking template suggestions into account?
I'm going to be going through the sandbox to try and make these a bit more consistent, and (after talking to @jenlampton in IRC) adding @see references from the preprocess function to the .html.twig template file, i.e.
Comment #7
c4rl CreditAttribution: c4rl commentedOne thing of note here is how the preprocess layer may change as part of the execution stack. We've come to acknowledge that the word "preprocess" means different things to different people. For themers, it means "prepare and alter variables for a template file." For developers concerned with runtime, it means "typically unnecessary layer of execution that we may or may not eventually use before invoking a given template."
So, might it be applicable to use the word "prepare" instead? This really gets to the core meaning of what happens here without invoking that this is literally "pre-processing."
UPDATE: Fixed typo in codeblock above, where I left "preprocess" instead of "prepare."
Let me know if I'm bikeshedding. :)
Comment #8
steveoliver CreditAttribution: steveoliver commentedYou probably meant
?
Sounds better, and maybe bikesheddy if we're not at the same time making the change in naming of 'preprocess', but at least it helps us clarify what we're doing at this point.
+1
Comment #9
star-szrI like prepare as well. I think this type of change should probably go through the core documentation queue, so we can come up with a standard on documenting preprocess functions.
If we go with "Prepare" for the preprocess functions, what about process functions? Or have we decided that process is going away?
Looking at http://drupal.org/node/1354#functions again, the current standards would give us something closer to "Preprocesses variables for…" or "Prepares variables for…".
Core documentation issue just created:
#1913208: [policy] Standardize template preprocess function documentation
Comment #10
star-szrClosing this issue, the core issue is ready for review:
#1913208: [policy] Standardize template preprocess function documentation