Tag Archives: developer-documentation

Nick Diego 1:39 pm on February 8, 2024
Tags: , developer-documentation   

Improving block development documentation: 2023 recap and a look ahead

Over the last year, a group of contributors has been working to improve the blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. development onboarding experience within the Block Editor Handbook. In this post, I wanted to take a moment and highlight the updates made, pinpoint areas for further refinement, and outline our focus for the next few months and ways you can help. 

Project overview

The initiative to enhance the Block Editor Handbook began in 2020, largely sparked by the Next Steps for Block Creation Documentation discussion on GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/. Since that time, the community has been consistently updating the content, with the most recent effort led by @juanmaguitar, @welcher, @mburridge, and myself.

You can view the tracking issues here:

In talking with prospective block developers, documentation was consistently one of the most recurrent pain points, especially for those who want to learn how to build custom blocks or extend the Editor using official resources. Improving the Getting Started section, as well as other extensibility docs, was a natural starting point in addressing this feedback. 

Here are some highlights from the work completed in the last eight months:

  • Landing page makeover: We’ve revamped the Handbook’s main page to make it more inviting and informative for those new to block development.
  • Updated Getting Started chapter: This section now offers a clearer path for beginners, including:
  • Expanded Curating the Editor Experience: Previously a single page, this topic was given its own dedicated section, with more updates coming in Q1 2024.
  • Block Development Examples: We launched a GitHub repository filled with practical examples of custom blocks and Editor extensions, complete with Playground previews and downloadable versions of each example. Contributions to the repository are welcomed.
  • More visuals: We’ve added diagrams and images throughout the Handbook to clarify key ideas.

Next steps

There is still plenty of work to do on the Getting Started chapter. A few additional articles for the Fundamentals section are in the works, and the Glossary and Frequently Asked Questions articles need updating. Following that, the How-to Guides chapter is the top priority, followed by Explanations. 

At this point, improvement to the Reference Guides chapter is ongoing, but no fundamental restructuring is planned in the near future. If you have ideas on how this section can be improved (much of it is autogenerated from in-code documentation), please share your suggestions. The current setup is not ideal, and it’s also not complete. Some code documentation is only accessible in the Gutenberg GitHub repository.

Get involved

The Block Editor Handbook contains over 400 published pages, and the effort taken in 2023 just scratches the surface. While that might seem daunting, improving the documentation is one of the easiest ways to contribute to the WordPress project, especially for quick fixes like typos or formatting. Feedback on existing content, such as the new block tutorial, is also invaluable. 

All documentation is hosted on the GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ GitHub repository. If you find an issue or wish to give feedback, please open a new issue there. If you would like to fix issues yourself, follow the Documentation Contributions guide to learn how to submit a pull request. You can see the list of all outstanding documentation issues using the [Type] Developer Documentation label.

If you experience any problems or have questions, reach out in the #core-editor or #docs SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. channels. You can also leave comments here or pingPing The act of sending a very small amount of data to an end point. Ping is used in computer science to illicit a response from a target server to test it’s connection. Ping is also a term used by Slack users to @ someone or send them a direct message (DM). Users might say something along the lines of “Ping me when the meeting starts.” me (@ndiego) directly.

Props to @greenshady for reviewing this post.

+make.wordpress.org/docs/

#block-developer-experience, #developer-documentation

zieladam 1:55 pm on October 12, 2022
Tags: , , , developer-documentation   

Block API changes in WordPress 6.1

WordPress 6.1 introduces several new BlockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. features available via the block.json file.

As a recap, the block.json file was introduced in WordPress 5.5 and has been encouraged as the canonical way of registering block types since the WordPress 5.8 release. Many of the recent Block API features, including the ones in this post, depend on block.json being available on the server.

PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher templates for rendering blocks

Before WordPress 6.1, the main output of a block would often be generated in either a JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. save function, or in a PHP render_callback function.

WordPress 6.1 adds a third way: a separate PHP template file. The path can be specified via the render property of block.json:

{
    "render": "file:./render.php"
}

If you don’t have a render_callback setting specified, then the template is used instead. It behaves similarly, but feels much more like traditional WordPress template handling.

The template path is prefixed with file: and relative to the location of the block.json file, following the npm specification.

The render.php template could look like this:

<p <?php echo get_block_wrapper_attributes(); ?>>
    <?php esc_html_e( 'Hello from a dynamic block!', 'my-plugin' ); ?>
</p>

Note: The entire file is used as a template, so there’s no need to define additional wrapping functions.

The following variables are available inside the template:

  • $attributes (array): The block attributes.
  • $content (string): The block default content.
  • $block (WP_Block): The block instance.

Use multiple scripts per block

The WordPress 6.1 version enables defining multiple script files in all relevant block.json entries: editScript, script, and viewScript. (Trac #56408) It’s now possible to pass a script handle registered with the wp_register_script function, a path to a JavaScript file relative to the block.json file, or an array with a mix of both:

{
    "editorScript": "file:./index.js",
    "script": "file:./script.js",
    "viewScript": [ "file:./view.js", "example-shared-view-script" ]
}

WordPress maintains a degree of backwards compatibility by passing along only the first (string) item to any existing code working with these values.

Note: Processing a single string requires a different code than processing an array of strings. Therefore, the WP_Block_Type class and the /wp/v2/block-types REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. endpoint deprecate accessing string values through their old names: editor_script, script, view_script, editor_style, and style.

The full array of scripts can be accessed via the following new properties of the WP_Block_Type class and the /wp/v2/block-types REST API endpoint:

  • editor_script_handles,
  • script_handles,
  • view_script_handles,
  • editor_style_handles, and
  • style_handles.

Furthermore, the scripts and styles registered in block.json will automatically be loaded for static and dynamic blocks in WordPress 6.1. Previously, the dynamic blocks were expected to register their assets.

Combined with the support for multiple stylesheets per block shipped with WordPress 5.9, this change enables developers to use multiple entries for all supported asset types.

Import individual coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. blocks from @wordpress/block-library

The import of individual core blocks (Pull request #42258) from the @wordpress/block-library npm package was enabled to help developers reduce the bundle size of their applications. Prior to this change, the use of a single core block required pulling in the entire set.

Individual core blocks can be imported in three different ways:

// You can import and automatically register the block:
import '@wordpress/block-library/build-module/verse/init';

// Or you can automatically register the block and reuse the reference:
import verseBlock from '@wordpress/block-library/build-module/verse/init';

// Or you can import the init function without registering the block…
import { init } from '@wordpress/block-library/build-module/verse';

// …and then register the block when needed:
const verseBlock = init();

Props to @gziolo, and @revgeorge for technical review, to @bph and @webcommsat for final review.

#6-1, #dev-notes, #dev-notes-6-1, #developer-documentation

Ari Stathopoulos 2:20 pm on December 15, 2021
Tags: , developer-documentation   

Using multiple stylesheets per block

Prior to WordPress 5.9, each blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. could (but not required to) have a stylesheet attached to it. The way blocks could register a stylesheet was by adding a style and/or editorStyle string in their block.json file.

In WordPress 5.9 we’re enhancing that behavior to allow using multiple stylesheets to be registered for each block. This change can benefit both block developers and theme developers, further reducing the total page-weight by only loading styles for blocks that exist on a page.

Blocks will now be able to register multiple stylesheets, and load styles from other blocks when needed. Themes will be able to add styles on a per-block basis instead of loading monolithic stylesheets that are force-loaded anywhere. This has a greater impact on block themes where stylesheets loading is optimised based on the page & layout contents, but can also be used by classic themes.

Usage for block developers

The style and editorStyle properties inside a block.json file can now be either a string, or an array of strings. Each string can be the handle of a previously registered stylesheet, or a path relative to the block.json file’s path, prefixed with file:./.

If you already have a block that uses a string, you needn’t worry. Everything will continue to work as expected. This is not a breaking change as the values can be either an array or a string, to maintain backward-compatibility.

This allows for complex blocks to reuse styles they need from other blocks without the need to duplicate those styles. For example, the comment-form block in WordPress 5.9 doesn’t need to duplicate the button block’s styles, and can instead reuse these styles by adding them to the block.json file:

{
 	"style": [
		"wp-block-post-comments-form",
		"wp-block-buttons",
		"wp-block-button"
	]
}

The same applies to the editorStyle value: Block developers can now define an array of styles, using the same format as the style value.

Usage for theme developers

Theme developers can also register stylesheets on a per-block basis. This way, no unnecessary styles will be rendered on a page unless the block is rendered (assuming the theme is a block-theme, or has opted-in to load separate stylesheets in the case of classic themes).

To do that, a new wp_enqueue_block_style() function was introduced.

The wp_enqueue_block_style function

The wp_enqueue_block_style function accepts 2 arguments, both of which are required:

$block_name

(string, required)

The name of the block – including its prefix/domain. For example the block_name of the paragraph block is core/paragraph.

$args

(array, required)

The arguments are the same used in the wp_enqueue_style function:

$args = array(
	'handle' => 'my-theme-p-styles',
	'src'    => get_theme_file_uri( 'styles/blocks/paragraph.css' ),
	...
);

In addition to the default wp_enqueue_style arguments, you can also add a path argument. This will allow WordPress to inline small assets when possible – if the theme opts-in to that behavior.

Example

Registering an extra stylesheet for the site-title block from a theme:

add_action( 'after_setup_theme', function() {
	// Same args used for wp_enqueue_style().
	$args = array(
		'handle' => 'my-theme-site-title',
		'src'    => get_theme_file_uri( 'assets/blocks/site-title.css' ),
	);

	// Add "path" to allow inlining asset if the theme opts-in.
	$args['path'] = get_theme_file_path( 'assets/blocks/site-title.css' );

	// Enqueue asset.
	wp_enqueue_block_style( 'core/site-title', $args );
} );

WordPress 5.9 enhances the way stylesheets for blocks get loaded. Though these changes have not been ported to block scripts yet, in future releases we plan to sync the two APIs, so block scripts can take advantage of them as well.

props @gziolo for reviewing this post.

#dev-notes, #developer-documentation

Ryan Welcher 5:38 pm on October 20, 2021
Tags: developer-documentation,   

Check out & contribute to the updated Gutenberg Examples

This week, a major portion of the work to update the Gutenberg Examples repository was completed. The repository blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. examples, while accurate, were out of date and didn’t reflect the most current approach to block registration.

These examples can be used in many ways. You can read through them to learn how to create blocks, check out the repository and modify them to see how they work, or use them as a starting point for your own blocks.

All example blocks now use block metadata files and leverage the most recent version of the Block API. Updates were also made to the developer experience to introduce ESlint and Prettier configurations that can be used by IDEs, and to leverage the most recent version of the @wordpress/scripts package.

Share your examples

While the existing examples cover a lot of topics and use cases, it would be great to expand the list and help more folks do more with blocks. In particular, examples covering more advanced block related topics or topics that are not strictly related to creating blocks but still part of the GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ developer toolkit, such as SlotFill, are very much needed.

If you’re looking for a way to contribute and grow community knowledge, please consider opening an issue or pull request with your example suggestion.

Special thanks to @mkaz and @gziolo for their help with code review and to @annezazu, @mkaz, @chanthaboune, @sparklingrobots, and @audrasjb for reviewing this post

#developer-documentation, #gutenberg

Jb Audras 9:04 pm on May 3, 2021
Tags: , developer-documentation, , , , helphub   

Docs Focus role & workflow during WordPress release cycle

This is a summary of a discussion which happened during previous Docs Team meetings and also a proposal for WordPress 5.8.

During the previous weekly Docs team meetings, a discussion started about how the Documentation team could be better involved during WordPress release cycles.

In recent years, all new versions of WordPress have had a person responsible for the “Docs” focus (@justinahinon for 5.3 and 5.5, @audrasjb for 5.4 and 5.7, @sncoker, @m_butcher and their cohort for 5.6). But even if all the dev notesdev note Each important change in WordPress Core is documented in a developers note, (usually called dev note). Good dev notes generally include a description of the change, the decision that led to this change, and a description of how developers are supposed to work with that change. Dev notes are published on Make/Core blog during the beta phase of WordPress release cycle. Publishing dev notes is particularly important when plugin/theme authors and WordPress developers need to be aware of those changes.In general, all dev notes are compiled into a Field Guide at the beginning of the release candidate phase. and the Field GuideField guide The field guide is a type of blogpost published on Make/Core during the release candidate phase of the WordPress release cycle. The field guide generally lists all the dev notes published during the beta cycle. This guide is linked in the about page of the corresponding version of WordPress, in the release post and in the HelpHub version page. (which are the main tasks of the Docs Focus) are published, the Docs team pointed out that it’s difficult for them to make sure all the end-user documentation (HelpHub) and the developer documentation (DevHub) are up to date after a new version is released.

WordPress release Docs Focus

@milana_cap (@zzap on SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/.) is the Docs Focus Lead for WordPress 5.8. The role of Docs Focus lead includes the responsibilities listed below. For each responsibility, one or more deputies will help the release Docs Focus lead but Milana Cap will remain the unique Docs reference person for the Release squad.

Developers notes wrangling on Make/CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.

  • Keep track of changes within the release that require dev notes
    (changes that require a dev notedev note Each important change in WordPress Core is documented in a developers note, (usually called dev note). Good dev notes generally include a description of the change, the decision that led to this change, and a description of how developers are supposed to work with that change. Dev notes are published on Make/Core blog during the beta phase of WordPress release cycle. Publishing dev notes is particularly important when plugin/theme authors and WordPress developers need to be aware of those changes.In general, all dev notes are compiled into a Field Guide at the beginning of the release candidate phase. must be labelled with the needs-dev-note workflow keyword)
  • Ensure all dev notes are written with enough time to proofread, reviewed, and published prior to the field guide (which is published by the Docs Focus lead at the same time as release candidaterelease candidate One of the final stages in the version release cycle, this version signals the potential to be a final release to the public. Also see alpha (beta). 1)
  • Coordinate with the participants of those tickets with the best understanding of the changes (the committercommitter A developer with commit access. WordPress has five lead developers and four permanent core developers with commit access. Additionally, the project usually has a few guest or component committers - a developer receiving commit access, generally for a single release cycle (sometimes renewed) and/or for a specific component., component maintainers, the contributor who owns the ticketticket Created for both bug reports and feature development on the bug tracker.) to draft dev notes
  • If a ticket participant is not available to write a dev note, finding someone to write one, or writing one yourself
  • Proofread and review dev notes as they are available from the Documentation Wrangling team
    • Verify code examples
    • Make suggestions for additional examples
    • Ensure the developer notes accurately and thoroughly describe the problem, solution, and identify proper usage of the changes

End-user documentation wrangling on HelpHub

  • Keep track of changes within the release that require changes on HelpHub
    (changes that require HelpHub changes (whether it’s a new page or just an update on existing ones) must be labelled with the needs-codex workflow keyword)
  • Ensure any documentation pages required for new features are created before the release
  • Ensure any existing documentation page for changes on existing features are ready to be updated (the day of the final release)
  • Write and publish the release version page on HelpHub
  • Update WordPress versions page on the Codex

Developer documentation wrangling on DevHub

  • Keep track of changes within the release that require changes on DevHub
    (changes that require DevHub changes –whether it’s a new page or just an update on existing ones– must be labelled with the needs-docs workflow keyword)
  • Ensure any documentation sections required for new features are ready to be updated (they are updated a few days after the final release, once the DevHub automatic parser has synchronized the documentation)
    • “More information” sections on DevHub (example)
    • BlockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. editor Developer Docs
  • Ensure any existing documentation sections for changes on existing features are ready to be updated (they are also updated a few days after the final release)
    • “More information” sections on DevHub
    • Block editor Developer Docs

Workflow

A new spreadsheet will be created by the docs focus lead. The previous spreadsheet was built for dev notes over all, with a simple “HelpHub” column. For WordPress 5.8, the Docs team proposed to use a tab for each responsibility: Dev notes, HelpHub and DevHub, so they can be equally wrangled. Also, Core changes from TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. will be separated from Block Editor changes from GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/.

Reviewed by @milana_cap and @jeffpaul.

#5-8, #developer-documentation, #devhub, #docs, #documentation, #helphub

Justin Ahinon 1:32 pm on January 25, 2021
Tags: , developer-documentation   

Block Editor Handbook: restructuring project update (25 January)

This is the second update for the project to restructure the developer documentation of the blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. editor. You can find the first update here.

The last two weeks we have been working on improving the documentation homepage. The PR for this has recently been merged, and the block editor now has a homepage with an improved structure. You can give a look at it here.

The next step for the next two weeks is to improve the table of contents of the documentation. The aim is to make it more consistent, and more complete.

The main exit to track changes to the table of contents is here. All contributions and ideas are welcome.

Thanks to all the people who contributed to the project; props to @mkaz @youknowriad @milana_cap @annezazu @paaljoachim.

#block-editor, #developer-documentation

Justin Ahinon 4:58 pm on January 15, 2021
Tags: , developer-documentation   

Block Editor Handbook: restructuring project update (15 January)

This post is the first in a series that will be published regularly on the Make/CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. blogblog (versus network, site). The purpose of this series is to keep everyone up to date on the progress of the BlockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. Editor Handbook restructuring project.

Currently, we are working on improving the handbook’s homepage. The goal is to make this page a real “Getting Started” page.

Someone coming to this page should be able to have a good overview of what the block editor is all about. They should also be able to find references to how to extend the block editor, how to contribute to it, or to the documentation of its main concepts.

The issue related to the handbook homepage improvement is here and here is the corresponding pull request.

Thanks to all the contributors who helped on the project this week 👏🏻.

#block-editor, #developer-documentation