This is intended to be quite a "high level" issue. Just a way to keep track of the various other meta issues and issues around improving the DX for drupal_render() and the renderable arrays (of doom), broadly categorised by use-case/demographic.
In short, this issue is about making it possible/simple to answer the following in a concise and accurate way that is true *in general* for all conceivable renderable arrays and can be immediately understood by developers who are new to Drupal:
- What does #type do?
- What does #theme do and how do #theme suggestions work?
- How do I know whether to use #theme or #type for elements that appear to be the same or at least very similar without resorting to looking through their code or finding examples? (#theme/#type 'table' I'm looking at you!)
- How and when should the "standard render attributes" #markup, #children, #prefix and #suffix that have nothing to do with theme() and element_info() be used?
- What is the "best" way to create structured data in a renderable array (ie. not a flat #markup attribute) to be rendered without invoking the theme system?
- What is the "best" way to wrap structured data in a renderable array both with and without the theme system?
- What is "drillability", why is it important and how do we achieve it?
Ideally I think we would want to be able to answer each one of these questions in no more than two sentences and without needing any sort of "disclaimer" listing special/edge cases and exceptions where core uses its own API inconsistently.
Site builders and contrib developers who want to use the render API in their own projects
Ensuring that the render API is easy to use and understand
These issues reduce the number of easy-to-introduce bugs or "gotchas" that developers building and rendering renderable arrays will encounter. This involves simplifying the API as much as possible and reducing the amount of "special casing" where renderable array properties are treated differently depending on contextual factors and the other properties on a given array.
- #2005970: In renderable arrays, #type should provide a #theme suggestion, similar to how drupal_prepare_form() works
- #1842326: Merge _theme_table_cell() into theme_table()
- #1595614: [meta] Remove all the theme functions and templates in core that simply output a link. Replace with #type 'link' render arrays
- #2025629: [meta] Ensure that all #theme/#theme_wrappers hooks provided by core are associated with a sensible, re-usable element #type
- #1804614: [meta] Consolidate theme functions and properly use theme suggestions in core
- #1804488: [meta] Introduce a Theme Component Library
- #1757550: [Meta] Convert core theme functions to Twig templates
- #2043649: Make all #type 'link' arrays 100% renderable, use #theme_wrappers if necessary
- #2053671: [meta] Name all theme functions that are only compatible with drupal_render() when nested within #theme_wrappers "foo_wrapper"
- #2060481: theme hooks are documented as responsible for rendering child elements in render arrays, most don't do this, many are incapable
- #1819284: [meta] Consolidate all form element container templates, and add theme_hook_suggestions
- #2272577: Make #base_type a standard way to extend #type in renderable arrays.
- #111079: Render API: Differentiate internal from user-settable renderable array attributes
Keeping documentation up to date
In some places the documentation for the render API is great but in others there are comments and docblocks that are demonstrably inaccurate or out of date. The DX around the render API could be improved greatly by keeping these up to date.
- #2015177: Update documentation around hook_element_info() to not say/imply element types are limited to the Form API
- #2024743: Document "reserved variables" for renderables to avoid conflicts with drupal_render(), the FAPI, and _theme()
Improving the experience of extending/processing/altering renderable arrays as they pass through the render API
Between when a renderable array is passed into drupal_render() and a "rendered" string is returned, there are multiple points where the data structure of the array can be intercepted and processed (sanitisation, resolving urls, etc..) and altered (modifying/adding content, etc..). These issues aim to keep that process as flexible and developer friendly as possible.
- #1985974: Make l() optionally return structured output
- #1876718: Allow modules to inject columns into tables more easily
- #2025259: drupal_render() should preserve the original render element in #original so pre and post render functions can access "raw" input
- #2044105: Introduce #alters for drupal_render()
- #2052253: [META] Add #render property to drupal_render() and convert #type "#pre_render -> #markup" calls to use it
- #1920886: drupal_render() should check if it's rendering a 'render element' and if so call drupal_render_children() (inline) instead
Reducing the amount of work required to modify rendered strings:
- #2008450: Provide for a drillable variable structure in Twig templates
- #1757550: [Meta] Convert core theme functions to Twig templates
- #1300744: Introduce #type 'links'
Changes to theme hooks:
- #2004872: [meta] Theme system architecture changes
Core contributors wanting to extend or improve the performance of the render API
Ensuring the render API is used in a consistent way within core and that it is maintainable
These issues are important as they help contributors plan improvements/changes to the render API without having to consider/accommodate a ton of "edge cases" in every decision. It also means that the "emergent behaviour" arising from each decision/patch will be more predictable, making it easier to achieve a stable and useable code base.
- #1876712: [meta] Convert all tables in core to new #type 'table'
- #2030243: Remove theme_file_upload_help() from the theme system
- #2046881: [meta] Avoid "early rendered" strings where beneficial to do so, build structured data to pass to drupal_render() once instead
- #2193613: [meta] full, organised test coverage for render element types and theme hooks
Performance optimisations for the render API
These issues have zero or minor impact on the functionality of the render API but will provide provable (profiled), replicable performance improvements.
- #2012800: \Drupal\Core\Render\Renderer::doRender() could be lazier about calling Element::children()
- #2046563: drupal_render() should check #cache after #type and #pre_render so that elements can set default cache behaviour
- #2067759: theme() could statically cache some of it's internals to avoid making function calls
Expanding the range of markup that can be safely cached.
- #1830588: [META] remove drupal_set_title() and drupal_get_title()
Reducing the amount of markup passed through the theme system (which can be expensive):
- #2004072: Add a non-themeable replacement for theme_image() and theme_image_style()
Extensions/modifications to the "internals" of the render API
These issues are ideas/proposals from core contributors directly modifying the internal behaviour of the render API (and the theme API where it's relevant to the render API as the latter invokes the former). Often these changes make sense in their own right but are blocked or hindered by other issues listed here. These issues may have little or no impact on the way the render API is invoked but improve the implementation nonetheless.
- #1843798: [meta] Refactor Render API to be OO
Bug fixes
Sometimes things are just broken.
- Not tracking anything at the moment.
Nearly done
These tasks may just need a change notice, backport or similar to be "complete".
- #2058761: PHP notice when #attributes is not set with #theme_wrappers 'container'
- #2015307: drupal_render() docs do not mention most of the base # attributes, adding default attributes to elements or how rendering works
Completed/closed tasks
- #2042285: #theme_wrappers should be able to have a unique set of variables per wrapper hook
- #2012812: drupal_render() can't distinguish between empty strings from theme() and no hook being matched
- #2061835: theme() doesn't enforce that what it returns is a string or FALSE
- #2068217: array('hook') syntax for suggestions is broken for #theme_wrappers
- #1979468: ".active" from linkGenerator(), l() and theme_links() forces an upper limit of per-page caching for all content containing linksAssigned to: Wim Leers
- #2006152: [meta] Don't call theme() directly anywhere outside drupal_render()
- #1886448: Rewrite the theme registry into a proper service
- #1985470: Remove theme_link()
- #1975442: drupal_render() should always return a string.
- #2012818: Remove #type 'markup'
- #2010672: Rename 'type' variable of theme_mark to 'status'
- #1828536: Rename 'type' variable of theme_item_list() to 'list_type'
- #1986116: Improve performance by replacing very small and simple templates and theme function with "Markup Utility Functions"
- #2041283: theme_status_report() is severely broken
- #2004286: Defer calls to drupal_get_* functions until printed inside a template by adding a RenderWrapper class
- #2030805: Make theme_status_report compatible with drupal_render()Assigned to: tsphethean
- #2009152: The default behaviour for drupal_render() when theme() is not called could be better at representing HTML as structured data
- #2031319: The documentation for theme() should be clearer about saying not to call it directly.
- #2009132: Remove #pre_render and #post_render from drupal_render() as it prevents proper Twig drillability