Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Covering All Features of Template Tags in Full Site Editing (FSE) #22724

Closed
epiqueras opened this issue May 29, 2020 · 25 comments
Closed

Covering All Features of Template Tags in Full Site Editing (FSE) #22724

epiqueras opened this issue May 29, 2020 · 25 comments
Assignees
Labels
[Status] In Progress Tracking issues with work in progress [Type] Overview Comprehensive, high level view of an area of focus often with multiple tracking issues

Comments

@epiqueras
Copy link
Contributor

epiqueras commented May 29, 2020

Covering All Features of Template Tags in Full Site Editing (FSE)

What are template tags?

Template tags are PHP functions used in traditional WordPress template files to display content from the database dynamically. For example, the the_author() tag prints the name of the current author. They are grouped by their "category," which is a loose mapping to the entity they refer to.

Some template tags are also compositions of a set of template tags.

How this relates to FSE.

We need to make sure that we have all the necessary blocks in place to accomplish everything possible in traditional templates using template tags. This issue aims to track our progress towards this goal and to surface areas where we lack functionality and require contributions.

Tracking Tables

Below we track all template tags alongside their block equivalent, if we need one (N/A otherwise), whether the development has started, and whether the current state of development matches or exceeds all the functionality provided by the tag.

Note that this list is just an educated guess. The idea is for everyone in the community, especially those very familiar with traditional theme development, to contribute to this list. There might be things we are missing. There might be things we could lose.

Also, note that some of these blocks could be split up into different blocks if the scope of their functionality creeps too much or people see a benefit in having more fine-grained control. For example, the Post Comments block could use a mechanism like the Query Loop block's to build a template for comments using Comment Author, Comment Date, and Comment Content blocks.

Template Tags Reference: https://codex.wordpress.org/Template_Tags

General

Template Tag Block Equivalent Started Completed
get_header() Template Part 🔲
get_footer() Template Part 🔲
get_sidebar() Template Part 🔲
get_template_part() Template Part 🔲
get_search_form() Search 🔲
wp_loginout() Authentication 🔲
wp_logout_url() Authentication 🔲 🔲
wp_login_url() Authentication 🔲 🔲
wp_login_form() Authentication 🔲
wp_lostpassword_url() Authentication 🔲 🔲
wp_register() Authentication 🔲 🔲
wp_meta() N/A N/A N/A
bloginfo() N/A N/A N/A
get_bloginfo() N/A N/A N/A
get_current_blog_id() N/A N/A N/A
wp_title() N/A N/A N/A
single_post_title() Post Title 🔲
post_type_archive_title() Archive Title 🔲
single_cat_title() Query Title 🔲
single_tag_title() Query Title 🔲
single_term_title() Query Title 🔲
single_month_title() Query Title 🔲
get_archives_link() Navigation 🔲
wp_get_archives() Navigation 🔲
calendar_week_mod() Calendar 🔲 🔲
get_calendar() Calendar 🔲 🔲
delete_get_calendar_cache() N/A N/A N/A
allowed_tags() N/A N/A N/A
wp_ajaxurl() N/A N/A N/A
wp_enqueue_script() N/A N/A N/A

Author

Template Tag Block Equivalent Started Completed
the_author() Post Author 🔲
get_the_author() Post Author 🔲
the_author_link() Post Author 🔲
get_the_author_link() Post Author 🔲
the_author_meta() Post Author 🔲
the_author_posts() Post Author 🔲
the_author_posts_link() Post Author 🔲
wp_dropdown_users() Post Author 🔲
wp_list_authors() Post Author 🔲
get_author_posts_url() Post Author 🔲

Bookmark

Template Tag Block Equivalent Started Completed
wp_list_bookmarks() Bookmarks 🔲 🔲
get_bookmark() Bookmarks 🔲 🔲
get_bookmark_field() Bookmarks 🔲 🔲
get_bookmarks() Bookmarks 🔲 🔲

Category

Template Tag Block Equivalent Started Completed
category_description() Query Description 🔲
the_category() Hierarchichal Taxonomies 🔲
the_category_rss() N/A N/A N/A
wp_dropdown_categories() Hierarchichal Taxonomies 🔲
wp_list_categories() Hierarchichal Taxonomies 🔲
tag_description() Query Description 🔲
the_tags() Flat Taxonomies 🔲 🔲
wp_generate_tag_cloud() Flat Taxonomies 🔲 🔲
wp_tag_cloud() Flat Taxonomies 🔲 🔲
term_description() Query Description
get_the_term_list() Flat Taxonomies 🔲 🔲
the_terms() Flat Taxonomies 🔲 🔲
the_taxonomies() Flat Taxonomies 🔲 🔲

Comment

Template Tag Block Equivalent Started Completed
cancel_comment_reply_link() Post Comments Form 🔲
comment_author_email() Post Comments 🔲
comment_author_email_link() Post Comments 🔲
comment_author() Post Comments 🔲
comment_author_IP() Post Comments 🔲
comment_author_link() Post Comments 🔲
comment_author_rss() N/A N/A N/A
comment_author_url() Post Comments 🔲
comment_author_url_link() Post Comments 🔲
comment_class() Post Comments 🔲
comment_date() Post Comments 🔲
comment_excerpt() Post Comments 🔲
comment_form_title() Post Comments Form 🔲
comment_form() Post Comments Form 🔲
comment_ID() Post Comments 🔲
comment_id_fields() Post Comments 🔲
comment_reply_link() Post Comments 🔲
comment_text() Post Comments 🔲
comment_text_rss() N/A N/A N/A
comment_time() Post Comments 🔲
comment_type() Post Comments 🔲
comments_link() Post Comments Link 🔲
comments_number() Post Comments Count 🔲
comments_popup_link() Post Comments Link 🔲 🔲
comments_popup_script() Post Comments Link 🔲 🔲
comments_rss_link() N/A N/A N/A
get_avatar() Post Comments 🔲
next_comments_link() Post Comments 🔲
paginate_comments_links() Post Comments 🔲
permalink_comments_rss() N/A N/A N/A
previous_comments_link() Post Comments 🔲
wp_list_comments() Post Comments 🔲

Link

Template Tag Block Equivalent Started Completed
the_permalink() Link 🔲 🔲
user_trailingslashit() N/A 🔲 🔲
permalink_anchor() Link 🔲 🔲
get_permalink() Link 🔲 🔲
get_post_permalink() Link 🔲 🔲
post_permalink() Link 🔲 🔲
get_page_link() Link 🔲 🔲
get_attachment_link() Link 🔲 🔲
wp_shortlink_header() N/A N/A N/A
wp_shortlink_wp_head() N/A N/A N/A
edit_bookmark_link() N/A N/A N/A
edit_comment_link() Post Comments 🔲 🔲
edit_post_link() Link 🔲 🔲
get_edit_post_link() Link 🔲 🔲
get_delete_post_link() Link 🔲 🔲
edit_tag_link() N/A N/A N/A
get_admin_url() Link 🔲 🔲
get_home_url() Link 🔲 🔲
get_site_url() Link 🔲 🔲
home_url() Link 🔲 🔲
site_url() Link 🔲 🔲
get_search_link() Link 🔲 🔲
get_search_query() Search 🔲
the_feed_link() Link 🔲 🔲

Post

Template Tag Block Equivalent Started Completed
body_class() N/A N/A N/A
next_image_link() N/A N/A N/A
next_post_link() Query Pagination 🔲
next_posts_link() Query Pagination 🔲
post_class() N/A N/A N/A
post_password_required() N/A N/A N/A
posts_nav_link() Query Pagination 🔲
previous_image_link() N/A N/A N/A
previous_post_link() Query Pagination 🔲
previous_posts_link() Query Pagination 🔲
sticky_class() N/A N/A N/A
the_content() Post Content 🔲
the_content_rss() N/A N/A N/A
the_excerpt() Post Excerpt 🔲
the_excerpt_rss() N/A N/A N/A
the_ID() N/A N/A N/A
the_meta() Post Field 🔲 🔲
the_title() Post Title 🔲
get_the_title() Post Title 🔲
the_title_attribute() N/A N/A N/A
the_title_rss() N/A N/A N/A
wp_link_pages() Query Pagination 🔲
get_attachment_link() Link 🔲 🔲
wp_get_attachment_link() Link 🔲 🔲
the_attachment_link() Link 🔲 🔲
the_search_query() Search 🔲
is_attachment() N/A N/A N/A
wp_attachment_is_image() N/A N/A N/A
wp_get_attachment_image() N/A N/A N/A
wp_get_attachment_image_src() N/A N/A N/A
wp_get_attachment_metadata() N/A N/A N/A
get_the_date() Post Date 🔲
the_date() Post Date 🔲
the_date_xml() Post Date 🔲
the_modified_author() Post Author 🔲
the_modified_date() Post Date 🔲
the_modified_time() Post Date 🔲
the_time() Post Date 🔲
the_shortlink() Link 🔲 🔲
wp_get_shortlink() Link 🔲 🔲

Post Thumbnail

Template Tag Block Equivalent Started Completed
has_post_thumbnail() Post Featured Image 🔲
get_post_thumbnail_id() Post Featured Image 🔲
the_post_thumbnail() Post Featured Image 🔲
get_the_post_thumbnail() Post Featured Image 🔲

Navigation Menu

Template Tag Block Equivalent Started Completed
wp_nav_menu() Navigation 🔲
walk_nav_menu_tree() N/A N/A N/A
@epiqueras epiqueras added [Status] In Progress Tracking issues with work in progress [Type] Overview Comprehensive, high level view of an area of focus often with multiple tracking issues [Feature] Full Site Editing labels May 29, 2020
@epiqueras epiqueras self-assigned this May 29, 2020
@rilwis
Copy link

rilwis commented Jun 9, 2020

Instead of making many blocks for template tags, it would be much better to have dynamic data connecting / mapping to basic blocks:

For example:

  • heading block is connected to post title to display it. So we have full design options from the heading block without duplicating for another post title block. Same can be applied to site title, site description
  • image block is connected to to post thumbnail to display featured image
  • paragraph block is connected to post excerpt

Another good thing is that users can choose which block they want to connect to. For example, users can connect post author to a paragraph block if they want to display it as a normal text or a heading block if they want to display it as a heading tag.

@epiqueras
Copy link
Contributor Author

That would be manipulating the sources of attributes through a UI.

I find it hard to imagine a UI where that wouldn't be overwhelmingly technical. Do you have any ideas?

We also have to keep in mind that attribute types are not directly compatible with the sources in question. A lot of these blocks process things before saving them or hide specific options that their sibling "regular" blocks have. For example, the post title, can't and doesn't support all the features of a heading.

@rilwis
Copy link

rilwis commented Jun 10, 2020

@epiqueras Yes, the UI might be the hardest part. I found the Beaver Themer team and Elementor Pro do this quite well. Here is a screenshot from Beaver Themer for reference:

Basically, they have a "toggler" near the input and clicking that shows list of supported sources.

Agree with the attributes/features.

@jffng
Copy link
Contributor

jffng commented Aug 28, 2020

I took a look at the theme we most recently developed, and noted which tags appeared that don't have an existing block in progress development to cover its functionality. Starred what I thought might be most useful to prioritize:

Template Tag Usage 🌟
the_permalink, get_permalink used to link the post / page tile, meta, and "continue reading" to the post in reference. 🌟
bloginfo, get_bloginfo used to render common site attributes like the name and description in both the markup and its attributes (e.g. in an aria-label). 🌟
post_password_required used in logic to determine whether to show post elements like post comments and thumbnail
post_type_archive_title used to render the archive page title. 🌟
the_ID used to specify html id attribute on posts and pages.
post_class self-evident 🌟
wp_get_attachment_image, wp_get_attachment_metadata self-evident

@aristath
Copy link
Member

aristath commented Sep 2, 2020

Posting a summary of our review during a block-based themes meeting:

General:

The loginout things would be useful to add login/logout links, but then again that would probably be most useful as a sub-item in the navigation block.

Bookmark:

These are no longer relevant

Comment:

The only thing missing is RSS, which can be added to comment-authors

Link:

In the context of FSE none of these will be needed... They can be helpers when building more complex PHP code, but on their own they don't mean anything. The only thing that could possibly be added is an "edit-post" link-block

As mentioned by @kjellr: "Most of the “Link” entries could probably just be dynamic links for use in block-based themes. A few might be worth including in the UI for the user to access, but many won’t."

As mentioned by @poena: the post comment link is still used fairly often

Post:

If the post-content block outputs the correct markup with the right ID, using post_class and all the things that dozens of plugins use, we should be OK.

One of the things that troubles us is the_meta(). Themes do all sorts of things with the appearance and functionality of this one... adding icons, styling, links etc.

@gziolo
Copy link
Member

gziolo commented Nov 26, 2020

Cross-referencing comment from #24762 (comment):

two things, though: "Query Title" is just "Page Title" and not tied to the query but tied to the template resolver. I think it should be added to the Milestone:4 Theme Blocks — #22724 instead

@mtias, it's already listed here as Query Title block and it is distinct from Post Title.

@mtias
Copy link
Member

mtias commented Nov 26, 2020

@gziolo by "Page Title" I meant https://developer.wordpress.org/reference/functions/the_archive_title/

@scruffian
Copy link
Contributor

scruffian commented Feb 2, 2021

The following template tags are used by Twenty Twenty-One, so they would be useful to get in place for TT1 Blocks

get_header()
get_footer()
get_template_part()
get_search_form()
wp_enqueue_script()
get_the_author()
the_author_meta()
get_author_posts_url()
comment_form()
get_avatar()
wp_list_comments()
the_permalink()
get_permalink()
edit_post_link()
get_edit_post_link()
home_url()
site_url()
get_search_query()
body_class()
post_class()
post_password_required()
the_content()
the_excerpt()
the_ID()
the_title()
get_the_title()
wp_link_pages()
is_attachment()
get_the_date()
has_post_thumbnail()
get_post_thumbnail_id()
the_post_thumbnail()
wp_nav_menu()

These two are also used but I guess they aren't relevant:

wp_get_attachment_image()
wp_get_attachment_metadata()

@scruffian
Copy link
Contributor

@pbking @MaggieCabrera @jffng and I went through these and this was what we came up with:

  • get_author_posts_url - This should be replaced by the author block, but doesn't have a feature for showing posts by this user, so we'd need to add that.

  • edit_post_link and get_edit_post_link - These aren't currently supported. Our feeling was that this was a pattern that we shouldn't support going forward, but it would be good to get more input on this.

Next Post / Prev Post Blocks

We need a way to add page titles to these blocks.

Featured Image Block

Featured images can have captions in Twenty Twenty-One, so I think we should add this to the block.

Search Template

  • We need a way to edit the template that is shown when there are no search results

Missing Templates

There are a few templates that don't seem to be customizable in the Site Editor:

  • The protected post password screen is customized in Twenty Twenty One
  • Image and attachment posts have a "Published in" link on them in Twenty Twenty One

We couldn't find a way to do this in the Site Editor.

Post Formats

There are custom excerpts for all post formats. Aside and status post formats also get a different treatment in the index template. There's no way (to our knowledge) to achieve this in the Site Editor. This raises the question of whether we want to continue supporting Post Formats going forward.

body_class

We are adding no-js, singular, hfeed, has-main-navigation and no-widgets classes to the body. We probably want to keep no-js, singular and hfeed but Gutenberg should probably add them to all themes.

I'm happy to add issues for each of these if that's helpful. cc @mtias

@aristath
Copy link
Member

  • get_author_posts_url - This should be replaced by the author block, but doesn't have a feature for showing posts by this user, so we'd need to add that.

No need to add anything to show posts by that user. Author-posts pages are archives, so if a theme has an archive.html template with a query block that inherits the global query (we already have that option in the query block) it will work out of the box.

  • edit_post_link and get_edit_post_link - These aren't currently supported. Our feeling was that this was a pattern that we shouldn't support going forward, but it would be good to get more input on this.

Agreed. There's already an edit-post link in the adminbar when users view an individual post.

Featured images can have captions in Twenty Twenty-One, so I think we should add this to the block.

+1

@MaggieCabrera
Copy link
Contributor

MaggieCabrera commented Feb 22, 2021

Next Post / Prev Post Blocks

We need a way to add page titles to these blocks.

The block already lets you add a page title as an option, but it needs some improvement: you can't add a line break between label and post title and you can't make the label a link to the next/prev post if you have the title also showing up. I opened an issue about this here

@scruffian
Copy link
Contributor

No need to add anything to show posts by that user. Author-posts pages are archives, so if a theme has an archive.html template with a query block that inherits the global query (we already have that option in the query block) it will work out of the box.

I couldn't find a way to add this link to the author bio though - unless I'm missing it?

@aristath
Copy link
Member

aristath commented Feb 22, 2021

I couldn't find a way to add this link to the author bio though - unless I'm missing it?

Ah you're right, my bad. I misread the previous post... Yes, we'll need to add a link to their posts somewhere 👍

@mtias
Copy link
Member

mtias commented Feb 24, 2021

We need a way to add page titles to these blocks.

Can you clarify what you mean by this?

Featured images can have captions in Twenty Twenty-One, so I think we should add this to the block.

I think captions on featured images is a bit odd / niche.

We need a way to edit the template that is shown when there are no search results

This is more a case of being able to edit the Query "no results" state in my mind.

Missing templates

I hope we can improve upon the dynamics of some of these instead of just copying what we currently do. Attachment templates in particular I think need a bit of a rethink.

Aside and status post formats also get a different treatment in the index template. There's no way (to our knowledge) to achieve this in the Site Editor.

Are these cosmetic or structural changes?

body_class

Let's have an issue for this. Also for post_class.

@scruffian
Copy link
Contributor

We need a way to add page titles to these blocks.
Can you clarify what you mean by this?

@MaggieCabrera opened an issue for this here: #29032

@scruffian
Copy link
Contributor

scruffian commented Feb 24, 2021

Are these cosmetic or structural changes?

The difference is that some excerpts show all the content, and others just show the first block from the post using twenty_twenty_one_print_first_instance_of_block

@scruffian
Copy link
Contributor

body_class
Let's have an issue for this. Also for post_class.

Done here: #29308

@mtias
Copy link
Member

mtias commented Feb 25, 2021

The difference is that some excerpts show all the content, and others just show the first block from the post using twenty_twenty_one_print_first_instance_of_block

There are a few things to consider here since we are talking about variations of the template used to show a post loop based on characteristics of a given post.

Possibly, some aspects could be absorbed in the blocks themselves with good defaults. For example, the excerpt block, content block, or post title block could have different default displays based on what post format is provided. This has the advantage of being simpler but is also opaque to the user and the theme template.

To allow full customization over things like "set a different font size for the excerpt if it comes from an aside", or "hide the title" it's either going to be through the cascade or by allowing template variations for the post loop. The UI for the latter can get very intricate but it can be worth exploring. Right now, for example, the template is implicit in the layout of the loop which is great for most common cases. But it can also make sense to have a more focused view, like an "edit template" button in the post loop toolbar opening a modal where you only focus on a single post at a time, and which could have some contextual filters for "format", "category", etc. How we store these within the post-loop block also needs some thinking. :)

cc @youknowriad @mcsf @ntsekouras @jameskoster

@jameskoster
Copy link
Contributor

To allow full customization over things like "set a different font size for the excerpt if it comes from an aside", or "hide the title" it's either going to be through the cascade or by allowing template variations for the post loop.

Could another option use template parts? We have Header and Footer areas, so perhaps Content could be an area option as well, with an affordance to specify the post type/format? Consequently an Archive template would look for the appropriate content template part (e.g. content-product, content-post, content-post-aside) based on the query.

@ianstewart
Copy link
Contributor

ianstewart commented Mar 2, 2021

In the spirit of "covering all features of template tags in … FSE" I was taking a look at "title" blocks today and wanted to highlight a couple items …

Post Title Block, Site Title Block

High-impact here means to me, "Could really boost themes, template part patterns, and query patterns, for end-users, themers, and patternmakers." (It's not a template-tag issue but Group Block: Add a ‘display horizontal’ option may do that as well in concert with the above settings.)

@carlomanf
Copy link

One of the things that troubles us is the_meta(). Themes do all sorts of things with the appearance and functionality of this one... adding icons, styling, links etc.

You are right that it can be re-purposed in many ways that will be tricky to cover, but #29173 covers one particular purpose of it.

@carolinan carolinan mentioned this issue Mar 16, 2021
5 tasks
@carolinan
Copy link
Contributor

There is only one single block that is marked as completed. How do we know what is needed for a block to be considered complete, and are completed blocks no longer experimental?

@mtias
Copy link
Member

mtias commented Mar 31, 2021

I'm going to do a review, but I think this issue probably exhausted its usefulness now. We have blocks that are ready (like site logo) but still need several improvements, which we should track on a specific site logo issue. As part of #28744 we should be deciding which ones are ready.

@scruffian
Copy link
Contributor

Yes, it's very hard to define "completed" since the scope isn't clear - we're not just copying the functionality from the old template tags. It might be useful to have overview issues for every core block though?

@mtias
Copy link
Member

mtias commented Apr 2, 2021

Going to close this one as its usefulness is mostly depleted. Let's focus now on organizing what blocks are available when
(#28744) and on the individual tracking issues for each block (like site logo #30406).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
[Status] In Progress Tracking issues with work in progress [Type] Overview Comprehensive, high level view of an area of focus often with multiple tracking issues
Projects
None yet
Development

No branches or pull requests