From 6e1d8261c43778f598f85ad3abbe4349fdf2a92e Mon Sep 17 00:00:00 2001 From: Matias Benedetto Date: Thu, 14 Sep 2023 16:33:18 -0300 Subject: [PATCH 01/10] adding first draft of docs --- lib/experimental/fonts/font-library/README.md | 248 ++++++++++++++++++ 1 file changed, 248 insertions(+) create mode 100644 lib/experimental/fonts/font-library/README.md diff --git a/lib/experimental/fonts/font-library/README.md b/lib/experimental/fonts/font-library/README.md new file mode 100644 index 00000000000000..5c432cdf3900d2 --- /dev/null +++ b/lib/experimental/fonts/font-library/README.md @@ -0,0 +1,248 @@ +## Font Library + +Font Library consists of a font manager that enables users to install, remove, and activate typographic fonts from various sources in WordPress. + +The Font Library is available globally, independently of the theme activated, similar to the Media Library. This list of installed fonts and their assets are site-wide available, and the users can select the fonts activated (available in the editor) for each theme. + +### Glossary + +- **Install font family**: Is to make a font family available to the user in the Font Library. The user will be able to activate and use the installed font families. +- **Activate font family**: Is to make it ready to use in the site or post editor. All the active fonts will appear in the font pickers so the user is able to use them in the site elements. +- **Deactivate font family**: Is to make a font family not usable. If a font family is not active it won't appear in the font pickers. +- **Uninstall font family**: Is to remove permanently the font family from the Font Library. + +### Diferent types of installations + +The library allow extenders to define how the fonts will be installed in WordPress. When users install a font family, its definition will always be saved to the database what can vary is where are the font face assets located. + +Let's see the different type of installations: + +#### Install a font with no font file assets (system fonts) +Let's say you want to install a font family that dosn't need any font assets to work, these types of fonts are usually called system fonts. You could define these font families like this: + +```json +{ + "name": "Humanist", + "slug": "humanist", + "fontFamily": "Seravek, 'Gill Sans Nova', Ubuntu, Calibri, 'DejaVu Sans', source-sans-pro, sans-serif", + +} +``` + +#### Install a font with external assets +Let's say you want to install a font family that need to add font faces using external font file assets. In this way your font face assets will be always serverd from the external url you indicated in `src` property of the font faces. Your font families should look like this: +```json +{ + "name": "Piazzolla", + "slug": "piazzolla", + "fontFamily": "Piazzolla, serif", + "fontFace": [ + { + "src": "http://fonts.gstatic.com/s/piazzolla/v33/N0b52SlTPu5rIkWIZjVKKtYtfxYqZ4RJBFzFfYUjkSDdlqZgy7LYxnLy1AHfAAy5.ttf", + "fontWeight": "400", + "fontStyle": "normal", + "fontFamily": "Piazzolla" + }, + ] +} +``` + +#### Install a font from external sources and serve it from your site +Let's say you want to install a font family that use assets located outside of your site and download it while installing to serve them always from your WordPress `/wp-content/fonts` folder. This can be useful if you want to avoid depending on external sites for technical or legal reasons. In that case you need to set the `downloadFromUrl` property on each font face. + +```json +{ + "name": "Piazzolla", + "slug": "piazzolla", + "fontFamily": "Piazzolla, serif", + "fontFace": [ + { + "downloadFromUrl": "http://fonts.gstatic.com/s/piazzolla/v33/N0b52SlTPu5rIkWIZjVKKtYtfxYqZ4RJBFzFfYUjkSDdlqZgy7LYxnLy1AHfAAy5.ttf", + "fontWeight": "400", + "fontStyle": "normal", + "fontFamily": "Piazzolla" + }, + ] +} +``` + +#### Install a font providing the font asset +Let's say you want to install a font family using font files you are providing in an http request. These font file assets will be stored in your WordPress `/wp-content/fonts` folder and they will always be served from your site. As the previous way this can be useful if you want to avoid depending on external sites for technical or legal reasons. You need to add the file to your http request and add a reference for it in the font face definition. + + +```json +{ + "name": "Piazzolla", + "slug": "piazzolla", + "fontFamily": "Piazzolla, serif", + "fontFace": [ + { + "uploadedFile": "request-file-id", + "fontWeight": "400", + "fontStyle": "normal", + "fontFamily": "Piazzolla" + }, + ] +} +``` + + +### Create a plugin to provide my font collection + +Creating a plugin to provide a font collection can be as simple as this: + +```php + + 'my-font-collection', + 'name' => 'My Font Collection', + 'description' => 'Demo about how to a font collection to your WordPress Font Library.', + 'data_json_file' => path_join( __DIR__, 'my-font-collection-data.json' ), +); + +if ( function_exists( 'wp_register_font_collection' ) ) { + wp_register_font_collection ( $my_config ); +} + +?> + +``` + +### API endpoints + +#### Install font families +Install a font family is to save a font definition in WordPress and make it available to be activated and used by the user. + +Save a font family may or may not include storing the font files assets localy to disk in `/wp-content/fonts` folder. That depends on how the font family sent to this endpoint is defined. + +``` +POST /wp-json/wp/v2/fonts +``` + +Example: + +#### Uninstall font families +Uninstall a font family is to remove the font definition from WordPress and make it unavailable for users to activate and save. + +If the font family being uninstalled is using local font file assets, those files will be removed from the `/wp-content/fonts` folder. + +``` +DELETE /wp-json/wp/v2/fonts +``` + +Example: + +#### Get font collections +Gets the list of fonts collections available. + +``` +GET /wp-json/wp/v2/fonts/collections +``` + +Example: + +#### Get a font collection +Get a particular font collection and its data. +``` +GET /wp-json/wp/v2/fonts/collections/ +``` + +Example: + +### Extensibility +Font Library is able to manage different font collections. A font collection is simply a list of font families ready to be installed by the user. Extenders can provide multiple typographic collections. + +#### Provide a font collection +To provide a font collection you need to call `wp_register_font_collection ()` function with your configuration as a parameter. + +Adding a font collection example: + +```php +$my_config = array ( + 'id' => 'my-font-collection', + 'name' => 'My Font Collection', + 'description' => 'Demo about how to a font collection to your WordPress Font Library.', + 'data_json_file' => path_join( __DIR__, 'my-font-collection-data.json' ), +); + +if ( function_exists( 'wp_register_font_collection' ) ) { + wp_register_font_collection ( $my_config ); +} +``` + +The Data JSON file for the collection created should look like this. +```json +{ + "fontFamilies": [ + ... + ], + "categories": [ + ... + ] +} +``` + +Example of a data JSON file providing 2 font families with 2 font faces each and 2 categories: + +```json +{ + "fontFamilies": [ + { + "name": "Montserrat", + "fontFamily": "Montserrat, sans-serif", + "slug": "montserrat", + "category": "sans-serif", + "fontFace": [ + { + "src": "http://fonts.gstatic.com/s/montserrat/v25/JTUHjIg1_i6t8kCHKm4532VJOt5-QNFgpCtr6Ew-Y3tcoqK5.ttf", + "fontWeight": "400", + "fontStyle": "normal", + "fontFamily": "Montserrat" + }, + { + "src": "http://fonts.gstatic.com/s/montserrat/v25/JTUFjIg1_i6t8kCHKm459Wx7xQYXK0vOoz6jq6R9aX9-p7K5ILg.ttf", + "fontWeight": "400", + "fontStyle": "italic", + "fontFamily": "Montserrat" + }, + ] + }, + { + "name": "Piazzolla", + "fontFamily": "Piazzolla, serif", + "slug": "piazzolla", + "category": "serif", + "fontFace": [ + { + "src": "http://fonts.gstatic.com/s/piazzolla/v33/N0b52SlTPu5rIkWIZjVKKtYtfxYqZ4RJBFzFfYUjkSDdlqZgy7LYxnLy1AHfAAy5.ttf", + "fontWeight": "400", + "fontStyle": "normal", + "fontFamily": "Piazzolla" + }, + { + "src": "http://fonts.gstatic.com/s/piazzolla/v33/N0b72SlTPu5rIkWIZjVgI-TckS03oGpPETyEJ88Rbvi0_TzOzKcQhZqx3gX9BRy5m5M.ttf", + "fontWeight": "400", + "fontStyle": "italic", + "fontFamily": "Piazzolla" + }, + ] + } + ], + "categories": [ + "sans-serif", + "serif" + ] +} +``` \ No newline at end of file From a899fe83b1a1aacac63c00ca1d4a3addea0fba0c Mon Sep 17 00:00:00 2001 From: Matias Benedetto Date: Thu, 14 Sep 2023 16:54:47 -0300 Subject: [PATCH 02/10] re-order sections --- lib/experimental/fonts/font-library/README.md | 152 +++++++++--------- 1 file changed, 76 insertions(+), 76 deletions(-) diff --git a/lib/experimental/fonts/font-library/README.md b/lib/experimental/fonts/font-library/README.md index 5c432cdf3900d2..436853b3b22dff 100644 --- a/lib/experimental/fonts/font-library/README.md +++ b/lib/experimental/fonts/font-library/README.md @@ -86,81 +86,6 @@ Let's say you want to install a font family using font files you are providing i } ``` - -### Create a plugin to provide my font collection - -Creating a plugin to provide a font collection can be as simple as this: - -```php - - 'my-font-collection', - 'name' => 'My Font Collection', - 'description' => 'Demo about how to a font collection to your WordPress Font Library.', - 'data_json_file' => path_join( __DIR__, 'my-font-collection-data.json' ), -); - -if ( function_exists( 'wp_register_font_collection' ) ) { - wp_register_font_collection ( $my_config ); -} - -?> - -``` - -### API endpoints - -#### Install font families -Install a font family is to save a font definition in WordPress and make it available to be activated and used by the user. - -Save a font family may or may not include storing the font files assets localy to disk in `/wp-content/fonts` folder. That depends on how the font family sent to this endpoint is defined. - -``` -POST /wp-json/wp/v2/fonts -``` - -Example: - -#### Uninstall font families -Uninstall a font family is to remove the font definition from WordPress and make it unavailable for users to activate and save. - -If the font family being uninstalled is using local font file assets, those files will be removed from the `/wp-content/fonts` folder. - -``` -DELETE /wp-json/wp/v2/fonts -``` - -Example: - -#### Get font collections -Gets the list of fonts collections available. - -``` -GET /wp-json/wp/v2/fonts/collections -``` - -Example: - -#### Get a font collection -Get a particular font collection and its data. -``` -GET /wp-json/wp/v2/fonts/collections/ -``` - -Example: - ### Extensibility Font Library is able to manage different font collections. A font collection is simply a list of font families ready to be installed by the user. Extenders can provide multiple typographic collections. @@ -245,4 +170,79 @@ Example of a data JSON file providing 2 font families with 2 font faces each and "serif" ] } -``` \ No newline at end of file +``` + +### Create a plugin to provide my font collection + +Creating a plugin to provide a font collection can be as simple as this: + +```php + + 'my-font-collection', + 'name' => 'My Font Collection', + 'description' => 'Demo about how to a font collection to your WordPress Font Library.', + 'data_json_file' => path_join( __DIR__, 'my-font-collection-data.json' ), +); + +if ( function_exists( 'wp_register_font_collection' ) ) { + wp_register_font_collection ( $my_config ); +} + +?> + +``` + +### API endpoints + +#### Install font families +Install a font family is to save a font definition in WordPress and make it available to be activated and used by the user. + +Save a font family may or may not include storing the font files assets localy to disk in `/wp-content/fonts` folder. That depends on how the font family sent to this endpoint is defined. + +``` +POST /wp-json/wp/v2/fonts +``` + +Example: + +#### Uninstall font families +Uninstall a font family is to remove the font definition from WordPress and make it unavailable for users to activate and save. + +If the font family being uninstalled is using local font file assets, those files will be removed from the `/wp-content/fonts` folder. + +``` +DELETE /wp-json/wp/v2/fonts +``` + +Example: + +#### Get font collections +Gets the list of fonts collections available. + +``` +GET /wp-json/wp/v2/fonts/collections +``` + +Example: + +#### Get a font collection +Get a particular font collection and its data. +``` +GET /wp-json/wp/v2/fonts/collections/ +``` + +Example: + From d839128c99417c179f83388a7174895126882922 Mon Sep 17 00:00:00 2001 From: Matias Benedetto Date: Thu, 14 Sep 2023 17:50:10 -0300 Subject: [PATCH 03/10] Adding font family and font faces to glossary. Correcting minor errors. --- lib/experimental/fonts/font-library/README.md | 22 ++++++++++--------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/lib/experimental/fonts/font-library/README.md b/lib/experimental/fonts/font-library/README.md index 436853b3b22dff..18e054f1a1d3b2 100644 --- a/lib/experimental/fonts/font-library/README.md +++ b/lib/experimental/fonts/font-library/README.md @@ -6,19 +6,21 @@ The Font Library is available globally, independently of the theme activated, si ### Glossary +- **Font family**: Is a typographic family that may include different variants. Typical examples are `Arial`, `Helvetica`, `Inter`. +- **Font face**: Is a typographic variant of a font family. Each font family may include one or more font faces. Each font face has some unique characteristics as font weight (light, regular, bold, etc.) and font style (italic, normal, etc.). Typical examples are `Helvetica bold italic`, `Inter light normal`. - **Install font family**: Is to make a font family available to the user in the Font Library. The user will be able to activate and use the installed font families. -- **Activate font family**: Is to make it ready to use in the site or post editor. All the active fonts will appear in the font pickers so the user is able to use them in the site elements. -- **Deactivate font family**: Is to make a font family not usable. If a font family is not active it won't appear in the font pickers. -- **Uninstall font family**: Is to remove permanently the font family from the Font Library. +- **Activate font family**: Is to make it ready to use in the site or post editor. All the active fonts will appear in the font pickers so the user can use them in the site elements. +- **Deactivate font family**: Is to make a font family unusable. If a font family is not active, it won't appear in the font pickers. +- **Uninstall font family**: Is to remove the font family from the Font Library permanently. -### Diferent types of installations +### Different types of installations -The library allow extenders to define how the fonts will be installed in WordPress. When users install a font family, its definition will always be saved to the database what can vary is where are the font face assets located. +The library allows extenders to define how WordPress will install fonts. When users install a font family, its definition will always be saved to the database. What can vary is where are the font face file assets stored. -Let's see the different type of installations: +Let's see the different types of installations: #### Install a font with no font file assets (system fonts) -Let's say you want to install a font family that dosn't need any font assets to work, these types of fonts are usually called system fonts. You could define these font families like this: +Let's say you want to install a font family that doesn't need any font assets to work; these fonts are usually called system fonts. You could define these font families like this: ```json { @@ -30,7 +32,7 @@ Let's say you want to install a font family that dosn't need any font assets to ``` #### Install a font with external assets -Let's say you want to install a font family that need to add font faces using external font file assets. In this way your font face assets will be always serverd from the external url you indicated in `src` property of the font faces. Your font families should look like this: +Let's say you want to install a font family that needs to add font faces using external font file assets. In this way, your font face assets will always be served from the external URL you indicated in the `src` property of the font faces. Your font families should look like this: ```json { "name": "Piazzolla", @@ -48,7 +50,7 @@ Let's say you want to install a font family that need to add font faces using ex ``` #### Install a font from external sources and serve it from your site -Let's say you want to install a font family that use assets located outside of your site and download it while installing to serve them always from your WordPress `/wp-content/fonts` folder. This can be useful if you want to avoid depending on external sites for technical or legal reasons. In that case you need to set the `downloadFromUrl` property on each font face. +Let's say you want to install a font family that uses assets located outside of your site and download it while installing to serve them always from your WordPress `/wp-content/fonts` folder. This can be useful if you want to avoid depending on external sites for technical or legal reasons. In that case, you need to set the `downloadFromUrl` property on each font face. ```json { @@ -67,7 +69,7 @@ Let's say you want to install a font family that use assets located outside of y ``` #### Install a font providing the font asset -Let's say you want to install a font family using font files you are providing in an http request. These font file assets will be stored in your WordPress `/wp-content/fonts` folder and they will always be served from your site. As the previous way this can be useful if you want to avoid depending on external sites for technical or legal reasons. You need to add the file to your http request and add a reference for it in the font face definition. +Let's say you want to install a font family using the font files you are providing in an HTTP request. These font file assets will be stored in your WordPress `/wp-content/fonts` folder and they will always be served from your site. As the previous way, this can be useful if you want to avoid depending on external sites for technical or legal reasons. You need to add the file to your HTTP request and add a reference for it in the font face definition. ```json From 601cc5d2bed5b69e0e440ed068d04ceb48cdc0b4 Mon Sep 17 00:00:00 2001 From: Vicente Canales Date: Mon, 27 Nov 2023 18:15:09 -0500 Subject: [PATCH 04/10] Rephrase according to feedback --- lib/experimental/fonts/font-library/README.md | 21 ++++++++----------- 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/lib/experimental/fonts/font-library/README.md b/lib/experimental/fonts/font-library/README.md index 18e054f1a1d3b2..74a91e0e1b5278 100644 --- a/lib/experimental/fonts/font-library/README.md +++ b/lib/experimental/fonts/font-library/README.md @@ -11,17 +11,15 @@ The Font Library is available globally, independently of the theme activated, si - **Install font family**: Is to make a font family available to the user in the Font Library. The user will be able to activate and use the installed font families. - **Activate font family**: Is to make it ready to use in the site or post editor. All the active fonts will appear in the font pickers so the user can use them in the site elements. - **Deactivate font family**: Is to make a font family unusable. If a font family is not active, it won't appear in the font pickers. -- **Uninstall font family**: Is to remove the font family from the Font Library permanently. +- **Uninstall font family**: Is to remove the font family from the Font Library permanently. ### Different types of installations The library allows extenders to define how WordPress will install fonts. When users install a font family, its definition will always be saved to the database. What can vary is where are the font face file assets stored. -Let's see the different types of installations: - +Review the following different types of installations to find what works best for your use case: #### Install a font with no font file assets (system fonts) -Let's say you want to install a font family that doesn't need any font assets to work; these fonts are usually called system fonts. You could define these font families like this: - +In a situation where you want to install a font family that doesn't need any font assets to work, these fonts are usually called system fonts. You can define these font families like this: ```json { "name": "Humanist", @@ -69,7 +67,7 @@ Let's say you want to install a font family that uses assets located outside of ``` #### Install a font providing the font asset -Let's say you want to install a font family using the font files you are providing in an HTTP request. These font file assets will be stored in your WordPress `/wp-content/fonts` folder and they will always be served from your site. As the previous way, this can be useful if you want to avoid depending on external sites for technical or legal reasons. You need to add the file to your HTTP request and add a reference for it in the font face definition. +Let's say you want to install a font family using the font files you are providing in an HTTP request. These font file assets will be stored in your WordPress `/wp-content/fonts` folder and they will always be served from your site. As the previous way, this can be useful if you want to avoid depending on external sites for technical or legal reasons. You need to add the file to your HTTP request and add a reference for it in the font face definition. ```json @@ -109,7 +107,7 @@ if ( function_exists( 'wp_register_font_collection' ) ) { } ``` -The Data JSON file for the collection created should look like this. +The Data JSON file for the collection created should look like this: ```json { "fontFamilies": [ @@ -121,7 +119,7 @@ The Data JSON file for the collection created should look like this. } ``` -Example of a data JSON file providing 2 font families with 2 font faces each and 2 categories: +Example of a data JSON file providing 2 font families, with 2 font faces each and 2 categories: ```json { @@ -174,10 +172,9 @@ Example of a data JSON file providing 2 font families with 2 font faces each and } ``` -### Create a plugin to provide my font collection - -Creating a plugin to provide a font collection can be as simple as this: +### Create a plugin to provide a font collection +Here's an example of a plugin that provides a font collection: ```php Date: Mon, 27 Nov 2023 18:18:09 -0500 Subject: [PATCH 05/10] Add font collection extensibility note --- lib/experimental/fonts/font-library/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/lib/experimental/fonts/font-library/README.md b/lib/experimental/fonts/font-library/README.md index 74a91e0e1b5278..9b8a084b3cbdde 100644 --- a/lib/experimental/fonts/font-library/README.md +++ b/lib/experimental/fonts/font-library/README.md @@ -90,7 +90,8 @@ Let's say you want to install a font family using the font files you are providi Font Library is able to manage different font collections. A font collection is simply a list of font families ready to be installed by the user. Extenders can provide multiple typographic collections. #### Provide a font collection -To provide a font collection you need to call `wp_register_font_collection ()` function with your configuration as a parameter. + +To provide a font collection you need to call `wp_register_font_collection ()` function with your configuration as a parameter. Any font collection you provide will be available as a new tab in the Font Library modal. Adding a font collection example: From e352d3edc38987b9e708e0deab3dd7eacb8e21cd Mon Sep 17 00:00:00 2001 From: Vicente Canales Date: Mon, 27 Nov 2023 18:28:25 -0500 Subject: [PATCH 06/10] Address installation type description feedback --- lib/experimental/fonts/font-library/README.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/lib/experimental/fonts/font-library/README.md b/lib/experimental/fonts/font-library/README.md index 9b8a084b3cbdde..195eb2bb266927 100644 --- a/lib/experimental/fonts/font-library/README.md +++ b/lib/experimental/fonts/font-library/README.md @@ -30,7 +30,7 @@ In a situation where you want to install a font family that doesn't need any fon ``` #### Install a font with external assets -Let's say you want to install a font family that needs to add font faces using external font file assets. In this way, your font face assets will always be served from the external URL you indicated in the `src` property of the font faces. Your font families should look like this: +In a situation where you want to install a font family that needs to add font faces using external font file assets, you can define font families like this: ```json { "name": "Piazzolla", @@ -47,8 +47,10 @@ Let's say you want to install a font family that needs to add font faces using e } ``` +Font Face assets will be served from the external URL provided in the `src` attribute. + #### Install a font from external sources and serve it from your site -Let's say you want to install a font family that uses assets located outside of your site and download it while installing to serve them always from your WordPress `/wp-content/fonts` folder. This can be useful if you want to avoid depending on external sites for technical or legal reasons. In that case, you need to set the `downloadFromUrl` property on each font face. +In order to install a font family that uses assets located outside of your site and download it while installing, to serve them from your WordPress `/wp-content/fonts` folder. Useful, for example, if you want to avoid depending on external sites for technical or legal reasons. It can be achieved by settings the `downloadFromUrl` property on each font face to the URL of the font. ```json { @@ -67,8 +69,7 @@ Let's say you want to install a font family that uses assets located outside of ``` #### Install a font providing the font asset -Let's say you want to install a font family using the font files you are providing in an HTTP request. These font file assets will be stored in your WordPress `/wp-content/fonts` folder and they will always be served from your site. As the previous way, this can be useful if you want to avoid depending on external sites for technical or legal reasons. You need to add the file to your HTTP request and add a reference for it in the font face definition. - +In a situation where you want to install a font family using the font files you are providing in an HTTP request. These font file assets will be stored in your WordPress `/wp-content/fonts` folder and they will always be served from your site. This can be useful, for example, if you want to avoid depending on external sites for technical or legal reasons. You need to add the file to your HTTP request and add a reference for it in the font face definition. ```json { @@ -91,7 +92,7 @@ Font Library is able to manage different font collections. A font collection is #### Provide a font collection -To provide a font collection you need to call `wp_register_font_collection ()` function with your configuration as a parameter. Any font collection you provide will be available as a new tab in the Font Library modal. +To provide a font collection you need to call `wp_register_font_collection()` function with your configuration as a parameter. Any font collection you provide will be available as a new tab in the Font Library modal. Adding a font collection example: From 4e692100410e77688480863b16ba4e139bbdddb8 Mon Sep 17 00:00:00 2001 From: Matias Benedetto Date: Mon, 5 Feb 2024 13:20:26 -0300 Subject: [PATCH 07/10] merge from trunk --- .../fonts/font-library => compat/wordpress-6.5/fonts}/README.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename lib/{experimental/fonts/font-library => compat/wordpress-6.5/fonts}/README.md (100%) diff --git a/lib/experimental/fonts/font-library/README.md b/lib/compat/wordpress-6.5/fonts/README.md similarity index 100% rename from lib/experimental/fonts/font-library/README.md rename to lib/compat/wordpress-6.5/fonts/README.md From 03895bf0a5b7df918cfd651c37181579de3184ef Mon Sep 17 00:00:00 2001 From: Matias Benedetto Date: Mon, 5 Feb 2024 14:47:00 -0300 Subject: [PATCH 08/10] improve text --- lib/compat/wordpress-6.5/fonts/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/lib/compat/wordpress-6.5/fonts/README.md b/lib/compat/wordpress-6.5/fonts/README.md index 195eb2bb266927..5f13394c1e4831 100644 --- a/lib/compat/wordpress-6.5/fonts/README.md +++ b/lib/compat/wordpress-6.5/fonts/README.md @@ -10,16 +10,16 @@ The Font Library is available globally, independently of the theme activated, si - **Font face**: Is a typographic variant of a font family. Each font family may include one or more font faces. Each font face has some unique characteristics as font weight (light, regular, bold, etc.) and font style (italic, normal, etc.). Typical examples are `Helvetica bold italic`, `Inter light normal`. - **Install font family**: Is to make a font family available to the user in the Font Library. The user will be able to activate and use the installed font families. - **Activate font family**: Is to make it ready to use in the site or post editor. All the active fonts will appear in the font pickers so the user can use them in the site elements. -- **Deactivate font family**: Is to make a font family unusable. If a font family is not active, it won't appear in the font pickers. -- **Uninstall font family**: Is to remove the font family from the Font Library permanently. +- **Deactivate font family**: Is to make a font family unusable. If a font family is inactive, it won't appear in the font pickers but will continue being listed in the font library. +- **Uninstall font family**: Is to remove the font family from the font library permanently. ### Different types of installations -The library allows extenders to define how WordPress will install fonts. When users install a font family, its definition will always be saved to the database. What can vary is where are the font face file assets stored. +The library allows extenders to define how WordPress installs fonts. When users install a font family, its definition will always be saved to the database. What can vary is where the font face file assets are stored. Review the following different types of installations to find what works best for your use case: -#### Install a font with no font file assets (system fonts) -In a situation where you want to install a font family that doesn't need any font assets to work, these fonts are usually called system fonts. You can define these font families like this: +#### Install a system font ( a font with no font file assets) +When you want to install a font family that doesn't need any font assets to work, these fonts are usually called system fonts. You can define these font families like this: ```json { "name": "Humanist", From b3561b0bbf7d6c52f1ed2cd90ef170ead5bc0421 Mon Sep 17 00:00:00 2001 From: Matias Benedetto Date: Mon, 5 Feb 2024 15:11:13 -0300 Subject: [PATCH 09/10] Add font collection to glossary --- lib/compat/wordpress-6.5/fonts/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/compat/wordpress-6.5/fonts/README.md b/lib/compat/wordpress-6.5/fonts/README.md index 5f13394c1e4831..6c95a0a5f2c315 100644 --- a/lib/compat/wordpress-6.5/fonts/README.md +++ b/lib/compat/wordpress-6.5/fonts/README.md @@ -12,6 +12,7 @@ The Font Library is available globally, independently of the theme activated, si - **Activate font family**: Is to make it ready to use in the site or post editor. All the active fonts will appear in the font pickers so the user can use them in the site elements. - **Deactivate font family**: Is to make a font family unusable. If a font family is inactive, it won't appear in the font pickers but will continue being listed in the font library. - **Uninstall font family**: Is to remove the font family from the font library permanently. +- **Font Collection**: A font collection is a list of font family definitions ready to be installed by the user. The font family definition is a fontFamily item in `theme.json` like format. ### Different types of installations From d9168b631177b7ecf5d3a4a9d44b69a8506e41ab Mon Sep 17 00:00:00 2001 From: Matias Benedetto Date: Tue, 6 Feb 2024 10:29:18 -0300 Subject: [PATCH 10/10] adding more content --- lib/compat/wordpress-6.5/fonts/README.md | 318 ++++++++++++++--------- 1 file changed, 191 insertions(+), 127 deletions(-) diff --git a/lib/compat/wordpress-6.5/fonts/README.md b/lib/compat/wordpress-6.5/fonts/README.md index 6c95a0a5f2c315..647007914dc80c 100644 --- a/lib/compat/wordpress-6.5/fonts/README.md +++ b/lib/compat/wordpress-6.5/fonts/README.md @@ -1,18 +1,200 @@ -## Font Library +# Font Library Font Library consists of a font manager that enables users to install, remove, and activate typographic fonts from various sources in WordPress. The Font Library is available globally, independently of the theme activated, similar to the Media Library. This list of installed fonts and their assets are site-wide available, and the users can select the fonts activated (available in the editor) for each theme. -### Glossary +The font library consist of 3 main components that are combined to make it work: the UI, the PHP API and the REST API. These docs cover them in that order. -- **Font family**: Is a typographic family that may include different variants. Typical examples are `Arial`, `Helvetica`, `Inter`. -- **Font face**: Is a typographic variant of a font family. Each font family may include one or more font faces. Each font face has some unique characteristics as font weight (light, regular, bold, etc.) and font style (italic, normal, etc.). Typical examples are `Helvetica bold italic`, `Inter light normal`. -- **Install font family**: Is to make a font family available to the user in the Font Library. The user will be able to activate and use the installed font families. -- **Activate font family**: Is to make it ready to use in the site or post editor. All the active fonts will appear in the font pickers so the user can use them in the site elements. -- **Deactivate font family**: Is to make a font family unusable. If a font family is inactive, it won't appear in the font pickers but will continue being listed in the font library. -- **Uninstall font family**: Is to remove the font family from the font library permanently. -- **Font Collection**: A font collection is a list of font family definitions ready to be installed by the user. The font family definition is a fontFamily item in `theme.json` like format. +## Using the Font Library + +The Font Library UI enables users to browse, install, uninstall, activate and de-activate fonts. + +### Browse installed fonts +The list of installed fonts features the fonts provided by the active theme (via `theme.json`) and the fonts installed using the font library. + +### Install fonts +Install font is to make a font family available to the user in the font library. When a font is installed its definition is stored in the database and their filee assets (if any) are stored in the file system.The fonts can be installed from a font collection or by uploading font file assets. Fonts installed using the font library are available system wide. + +#### Install fonts from a font collection +To install a font from a font collection the user needs to browse the font collection tab, select the font family, then check all the variants desired, and, finally, tap 'Install' button. + +#### Install fonts by uploading files +To install a font by uploading font files, the user needs to navigate the 'Upload' tab of the font library modal and drag and drop or select the font files of the font family to install. + +### Uninstall fonts +Uninstall a font family is removing a font family from the font library permanently. It means that the font definition is removed from the database, and the font assets, if any, are removed from the file-system. + +### Activate and de-activate fonts +When a font family is activated, the font defintion is added to the [Global Styles](/packages/edit-site/src/components/global-styles). Font families listed in global styles are rendered to pages and become available in the font pickers, so they can be applied to any element using the editor. + +When a font family is de-activated the font definition is removed from the global styles, so it won't be rendered on the frontend. The unactive fonts are still available on the font library and can be re-activated at any time. + +When + + +## PHP API + + +### Font Collections +A font collection is a list of font family definitions ready to be installed by the user. The font family definition is a fontFamily item in `theme.json` like format. The font collections are presented to the users in the editor so one can choose whether to install a font family to their WordPress site. + +The only responsibility of a font collection is to present a list of font families in a correct format. Font collections are not in charge of installing the fonts; they just list a group of font families so users can choose the one they want to install. If the font family includes font faces, those font faces should have links to bundled (e.g: in a plugin assets) or external (e.g: from a CDN) font assets that will be downloaded or linked when the font family is installed. + +#### Register a font collection +Register a font collection means providing a user a new list of fonts from one can select and install fonts. When a font collection is registered it is featured as a new tab in the font library modal and it's fetcheable using the `/font-collections/` REST API endpoint. + +To register a font collection you need to use `wp_register_font_collection` function. + +##### Register a font collection using PHP only +Example: +```php +$font_families = [ + array( + 'font_family_settings' => ( + array ( + 'fontFamily' => 'Piazzolla, serif', + 'slug' => 'paizzolla', + 'name' => 'Piazzolla', + 'fontFace' => array ( + array ( + 'fontFamily' => 'Piazzolla', + 'fontWeight' => '400' + 'fontStyle' => 'normal' + 'src' => path_join( plugin_dir_path( __FILE__ ), "fonts/piazzolla400normal.woff2" ) + ) + ) + ) + ), + 'categories' => [ 'system-ui' ], + ), + array( + 'font_family_settings' => ( + array ( + 'fontFamily' => 'Arial, Helvetica, Tahoma, Geneva, sans-serif', + 'slug' => 'arial', + 'name' => 'Arial', + ) + ), + 'categories' => [ 'sans-serif' ], + ), +]; + +$categories = [ + array( + 'slug' => 'serif', + 'name' => 'Serif', + ), + array( + 'slug' => 'sans-serif', + 'name' => 'Sans Serif', + ), +]; + +$config = array ( + 'name' => 'My sytem fonts collection', + 'description' => 'Stacks of modern systems fonts, not font face assets needed. The look will vary on each system.', + 'font_families' => $font_families, + 'categories' => $categories, +); + +function register_my_collection(){ + wp_register_font_collection ( 'my-font-foundry', $config ); +} + +add_action( 'init', 'register_my_collection' ); +``` + +##### Register a font collection using a JSON file + +Example using a local JSON file: +```php +function register_my_collection(){ + wp_register_font_collection ( 'my-font-foundry', path_join( __DIR__, 'my-collection.json' ) ); +} + +add_action( 'init', 'register_my_collection' ); +``` + +Example using a JSON from an URL: +```php +function register_my_collection(){ + wp_register_font_collection ( 'my-font-foundry', 'https://example.com/fonts/my-collection.json' ); +} + +add_action( 'init', +``` + +`my-collection.json` file example: + +```json +{ + "$schema": "https://schemas.wp.org/trunk/font-collection.json", + "name": "My Font Foundry Collection", + "decription": "The font offered by My Font Foundry", + "categories": [ + { "id": "sans-serif", "name": "Sans Serif" }, + { "id": "serif", "name": "Serif" }, + ], + "font_families": [ + { + "font_family_settings": { + "name": "Aboreto", + "fontFamily": "Aboreto, system-ui", + "slug": "aboreto", + "fontFace": [ + { + "src": "https://fonts.gstatic.com/s/aboreto/v2/5DCXAKLhwDDQ4N8blKHeA2yuxSY.woff2", + "fontWeight": "400", + "fontStyle": "normal", + "fontFamily": "Aboreto", + "preview": "https://s.w.org/images/fonts/17.6/previews/aboreto/aboreto-400-normal.svg" + } + ], + "preview": "https://s.w.org/images/fonts/17.6/previews/aboreto/aboreto.svg" + }, + "categories": ["sans-serif"] + }, + { + "font_family_settings": { + "name": "Abril Fatface", + "fontFamily": "Abril Fatface, system-ui", + "slug": "abril-fatface", + "fontFace": [ + { + "src": "https://fonts.gstatic.com/s/abrilfatface/v23/zOL64pLDlL1D99S8g8PtiKchm-VsjOLhZBY.woff2", + "fontWeight": "400", + "fontStyle": "normal", + "fontFamily": "Abril Fatface", + "preview": "https://s.w.org/images/fonts/17.6/previews/abril-fatface/abril-fatface-400-normal.svg" + } + ], + "preview": "https://s.w.org/images/fonts/17.6/previews/abril-fatface/abril-fatface.svg" + }, + "categories": ["serif"] + }, + ] +} +``` + +#### Unregister a font collection +To unregister a font collection you need to add an action calling `wp_unregister_font_collection` with the font collection slug as the only parameter. The unregistered font collections won't appear as a font library modal tab and it won't be listed on the `/font-collections/` REST API endpoint. + +Example: +```php +function unregister_google_fonts(){ + wp_unregister_font_collection ( 'google-fonts' ); +} +add_action( 'init', 'unregister_google_fonts' ); +``` + +### Assets storage + +**TODO:** add the `font_dir` docs. + + + +## Rest API ### Different types of installations @@ -88,124 +270,6 @@ In a situation where you want to install a font family using the font files you } ``` -### Extensibility -Font Library is able to manage different font collections. A font collection is simply a list of font families ready to be installed by the user. Extenders can provide multiple typographic collections. - -#### Provide a font collection - -To provide a font collection you need to call `wp_register_font_collection()` function with your configuration as a parameter. Any font collection you provide will be available as a new tab in the Font Library modal. - -Adding a font collection example: - -```php -$my_config = array ( - 'id' => 'my-font-collection', - 'name' => 'My Font Collection', - 'description' => 'Demo about how to a font collection to your WordPress Font Library.', - 'data_json_file' => path_join( __DIR__, 'my-font-collection-data.json' ), -); - -if ( function_exists( 'wp_register_font_collection' ) ) { - wp_register_font_collection ( $my_config ); -} -``` - -The Data JSON file for the collection created should look like this: -```json -{ - "fontFamilies": [ - ... - ], - "categories": [ - ... - ] -} -``` - -Example of a data JSON file providing 2 font families, with 2 font faces each and 2 categories: - -```json -{ - "fontFamilies": [ - { - "name": "Montserrat", - "fontFamily": "Montserrat, sans-serif", - "slug": "montserrat", - "category": "sans-serif", - "fontFace": [ - { - "src": "http://fonts.gstatic.com/s/montserrat/v25/JTUHjIg1_i6t8kCHKm4532VJOt5-QNFgpCtr6Ew-Y3tcoqK5.ttf", - "fontWeight": "400", - "fontStyle": "normal", - "fontFamily": "Montserrat" - }, - { - "src": "http://fonts.gstatic.com/s/montserrat/v25/JTUFjIg1_i6t8kCHKm459Wx7xQYXK0vOoz6jq6R9aX9-p7K5ILg.ttf", - "fontWeight": "400", - "fontStyle": "italic", - "fontFamily": "Montserrat" - }, - ] - }, - { - "name": "Piazzolla", - "fontFamily": "Piazzolla, serif", - "slug": "piazzolla", - "category": "serif", - "fontFace": [ - { - "src": "http://fonts.gstatic.com/s/piazzolla/v33/N0b52SlTPu5rIkWIZjVKKtYtfxYqZ4RJBFzFfYUjkSDdlqZgy7LYxnLy1AHfAAy5.ttf", - "fontWeight": "400", - "fontStyle": "normal", - "fontFamily": "Piazzolla" - }, - { - "src": "http://fonts.gstatic.com/s/piazzolla/v33/N0b72SlTPu5rIkWIZjVgI-TckS03oGpPETyEJ88Rbvi0_TzOzKcQhZqx3gX9BRy5m5M.ttf", - "fontWeight": "400", - "fontStyle": "italic", - "fontFamily": "Piazzolla" - }, - ] - } - ], - "categories": [ - "sans-serif", - "serif" - ] -} -``` - -### Create a plugin to provide a font collection - -Here's an example of a plugin that provides a font collection: -```php - - 'my-font-collection', - 'name' => 'My Font Collection', - 'description' => 'Demo about how to a font collection to your WordPress Font Library.', - 'data_json_file' => path_join( __DIR__, 'my-font-collection-data.json' ), -); - -if ( function_exists( 'wp_register_font_collection' ) ) { - wp_register_font_collection ( $my_config ); -} - -?> - -``` ### API endpoints