On #2148255: [meta] Make better D8 api.d.o landing page, linked to high-level overview topics, and put it in Core api.php files, we made a patch that included a stub Topic page for api.drupal.org (i.e., a @defgroup) titled:

Theme system and Render API

This can be found in file core/modules/system/core.api.php where it says

@defgroup theme_render

The documentation to go on this page needs to be written. The idea is:

a) Write a few paragraphs about the topic.

b) Link to more detailed documentation on
https://drupal.org/developing/api/8

c) If the more detailed documentation does not yet exist, create stub page(s), link to the stub pages, and add a note to this issue stating that the stub pages need to be filled out.

d) If the topic has related classes, interfaces, and functions -- appropriate for an overview -- add

@ingroup theme_render

to their documentation headers. That will make these classes etc. show up on the Topic page on api.drupal.org. Only include classes/functions that are appropriate for an overview page please!

For more info -- documentation standards for @defgroup/@ingroup:
https://drupal.org/coding-standards/docs#defgroup

Files: 
CommentFileSizeAuthor
#8 2216549-render-theme-docs-8.patch17.86 KBjhodgdon
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 72,286 pass(es). View
#7 interdiff.txt1.15 KBjhodgdon
#3 2216549-render-theme-docs-3.patch17.85 KBjhodgdon
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 69,876 pass(es). View

Comments

jhodgdon’s picture

Issue tags: +beta target
jhodgdon’s picture

Assigned: Unassigned » jhodgdon

This seems like the next topic to work on... taking it on!

jhodgdon’s picture

Status: Active » Needs review
Related issues: +#1617948: [policy for now] New standard for documenting form/render elements and properties
FileSize
17.85 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 69,876 pass(es). View

Here's a first patch -- please review and provide constructive criticism, pointing out all the things I got wrong, omitted to mention, etc. Thanks!

Note that I updated both the new Theme and Render API overview topic, which is linked from the D8 api.drupal.org landing page, and the "Themeable" topic, which isn't (it needed some help).

Boy it would be nice if we had an automatically-generated list of documented render API elements and properties... sigh.
#1617948: [policy for now] New standard for documenting form/render elements and properties
Any hope of circling back on that one?

Cottser’s picture

Issue tags: +Twig

Thanks @jhodgdon! I don't have time to review this right this minute but I'm tagging this issue so it shows up on http://drupaltwig.org, this looks like really important documentation to get in place for the theme system.

steveoliver’s picture

Issue tags: -Twig

Excellent work, @jhodgdon! Very helpful clarifications and grammar clean-ups. Technically, I see no issues. Otherwise:

  1. +++ b/core/modules/system/core.api.php
    @@ -372,12 +372,73 @@
    + *
    + * For further information on the Theme and Render APIs, see:
    + * - https://drupal.org/documentation/theme
    + * - https://drupal.org/developing/modules/8
    + * - https://drupal.org/node/722174
    + * - https://drupal.org/node/933976
    + * - https://drupal.org/node/930760
    + *
    + * @todo Check these links. Some are for Drupal 7, and might need updates for
    + *   Drupal 8.
    

    Yes, the last three links need updates/review for Drupal 8.

  2. +++ b/core/modules/system/theme.api.php
    @@ -3,73 +3,90 @@
    + * Functions and templates for the user interface that themes can override.
    + *
    + * Drupal's theme system ideally allows a theme to have complete control over
    + * the appearance of the site, which includes both the markup and the CSS used
    + * to style the markup. For this system to work, modules, instead of writing
    

    Why the word "ideally"? Maybe "Drupal's theme system allows a theme to have nearly complete control over the appearance of the site,..." ?

  3. +++ b/core/modules/system/theme.api.php
    @@ -86,32 +103,51 @@
    + * @section sec_suggestions Theme hook suggestions
    + * In some cases, instead of calling the base theme hook implementation (either
    + * the default provided by the module that defined the hook, or the override
    + * provided by the theme), the theme system will instead look for "suggestions"
    + * of other hook names to look for. Suggestions can be specified in several
    + * ways:
    + * - In a render array, the '#theme' property (which gives the name of the hook
    + *   to use) can be an array of theme hook names instead of a single hook name.
    + *   In this case, the render system will look first for the highest-priority
    + *   hook name, and if no implementation is found, look for the second, and so
    + *   on. Note that the highest-priority suggestion is at the end of the array.
    + * - In a render array, the '#theme' property can be set to the name of a hook
    + *   with a '__SUGGESTION' suffix. For example, in search results theming, the
    + *   hook 'item_list__search_results' is given. In this case, the render system
    + *   will look for theme templates called item-list--search-results.html.twig,
    + *   which would only be used for rendering item lists containing search
    + *   results, and if this template is not found, it will fall back to using the
    + *   base item-list.html.twig template. This type of suggestion can also be
    + *   combined with providing an array of theme hook names as described above.
    + * - A module can implement hook_theme_suggestions_HOOK(). This allows the
    + *   module that defines the theme template to dynamically return an array
    + *   containing specific theme hook names (presumably with '__' suffixes as
    + *   defined above) to use as suggestions. For example, the Search module
    + *   does this in search_theme_suggestions_search_result() to suggest
    + *   search_result__PLUGIN as the theme hook for search result items, where
    + *   PLUGIN is the machine name of the particular search plugin type that was
    + *   used for the search (such as node_search or user_search).
    + *
    + * @section sec_alternate_suggestions Suggesting Alternate Hooks
    + * Modules can also alter the theme suggestions provided using the mechanisms
    + * of the previous section. There are two hooks for this: the
    + * theme-hook-specific hook_theme_suggestions_HOOK_alter() and the generic
    + * hook_theme_suggestions_alter(). These hooks get the current list of
    + * suggestions as input, and can change this array (adding suggestions and
    + * removing them).
    + *
    

    The title of the second section seems a little too similar to the first. Instead of "Suggesting Alternate Hooks" maybe use the heading "Altering Theme Hook Suggestions" ?

steveoliver’s picture

Issue tags: +Twig

Adding Twig tag I accidentally removed with last comment.

jhodgdon’s picture

FileSize
1.15 KB
17.86 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 70,270 pass(es). View

Thanks for the review! Addressed #5 points 2 and 3. Point 1 seems like you agree that the @todo needs to stay in there?

jhodgdon’s picture

FileSize
17.86 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 72,286 pass(es). View

Slight reroll for clean apply.

Can someone review this patch so we can get this in? Please?

jhodgdon’s picture

steveoliver’s picture

Status: Needs review » Needs work

Thanks, @jhodgdon.

Looking at those links again, I see all three pages are very tightly coupled to D7, and instead of rewriting them, I think new pages should be created for D8 and used in this patch (linked from the other pages where appropriate).

jhodgdon’s picture

Status: Needs work » Needs review

Rewriting the pages on drupal.org is out of scope for this issue. Would it be OK to leave the links as they are for now, and if someone eventually adds a community documentation page that explains things better for D8, we can fix the link then? Right now, we have nothing on api.drupal.org about this at all... we cannot hold up this patch while we wait for full documentation to be written.

That is, in any case, why we have this note in the current patch:

+ *
+ * @todo Check these links. Some are for Drupal 7, and might need updates for
+ *   Drupal 8.
  * @}
steveoliver’s picture

Status: Needs review » Reviewed & tested by the community

Fair enough. Those links are as good as they get for now, and this patch is full of nothing but helpful clarifications and additions to our docs. RTBC.

jhodgdon’s picture

Assigned: jhodgdon » Unassigned

Thanks! Unassigning myself to avoid "I'm committing this" vs. "I worked on this" committer confusion.

webchick’s picture

Status: Reviewed & tested by the community » Fixed

Sorry for the delay on this, this looks really great.

Committed and pushed to 8.x. Thanks!

  • Commit 71acbe3 on 8.x by webchick:
    Issue #2216549 by jhodgdon, steveoliver: Fill in @defgroup/topic docs...
jhodgdon’s picture

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.