Skip to content

Commit

Permalink
Merge pull request #868 from humanmade/676-documentation-linting-fixes
Browse files Browse the repository at this point in the history 
Reformat docs files after linting
  • Loading branch information
@mikelittle
mikelittle authored Nov 4, 2024
2 parents ff856a6 + 23b2c42 commit c84429f
Show file tree
Hide file tree
Showing 10 changed files with 293 additions and 237 deletions.
8 changes: 5 additions & 3 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
# CMS

![](./assets/banner-cms.png)
![CMS banner](./assets/banner-cms.png)

The CMS (Content Management System) module is the foundational component of Altis. It provides the means of creating, editing and delivering your data.
The CMS (Content Management System) module is the foundational component of Altis. It provides the means of creating, editing and
delivering your data.

The core experience is provided by [WordPress](https://wordpress.org/), with additional features tied in to create a smarter more fully featured CMS that's ready for enterprise.
The core experience is provided by [WordPress](https://wordpress.org/), with additional features tied in to create a smarter more
fully featured CMS that's ready for enterprise.
73 changes: 39 additions & 34 deletions docs/block-editor.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,21 +9,23 @@ WordPress's built in Reusable Blocks feature has been supercharged in Altis with
* Provide a much more seamless implementation of reusable blocks into enterprise-level setups and workflows.
* Provide an improved user interface that allows for better block discovery, including search and filtering.

Within the block editor it's possible to reuse blocks of content across multiple posts or pages. In Altis these blocks can be more easily be created and managed from a single location and any updates will be reflected everywhere the block is used.
Within the block editor it's possible to reuse blocks of content across multiple posts or pages. In Altis these blocks can be more
easily be created and managed from a single location and any updates will be reflected everywhere the block is used.

You can toggle these enhancements on or off in your `composer.json` file by setting the `reusable-blocks` property for the CMS module to `true` or `false`.
You can toggle these enhancements on or off in your `composer.json` file by setting the `reusable-blocks` property for the CMS
module to `true` or `false`.

```json
{
"extra": {
"altis": {
"modules": {
"cms": {
"reusable-blocks": false
}
}
}
}
"extra": {
"altis": {
"modules": {
"cms": {
"reusable-blocks": false
}
}
}
}
}
```

Expand All @@ -33,17 +35,21 @@ Altis Reusable Blocks includes features and improvements both for the creation a

#### Relationship and usage tracking

Keep track of all usages of reusable blocks within your posts. Within the edit screen for your reusable blocks, you will find the Relationships sidebar with a paginated view of all the posts that are using the reusable block that you are currently editing.
Keep track of all usages of reusable blocks within your posts. Within the edit screen for your reusable blocks, you will find the
Relationships sidebar with a paginated view of all the posts that are using the reusable block that you are currently editing.

On the reusable blocks post list table, you can see at a quick glance the usage count for that reusable block.

#### Admin Bar and Menu

By default, reusable blocks are somewhat hidden and can only be accessed from a submenu item in the block editor.
By default, reusable blocks are somewhat hidden and can only be accessed from a sub-menu item in the block editor.
With Altis Reusable Blocks, however, reusable blocks are upgraded to first-party citizens in the admin area.

As with every other content type, the admin menu on the left contains a dedicated submenu for reusable blocks, offering shortcuts to see all existing reusable blocks, to create a new reusable block, and to see and manage categories, as well as any other publicly available taxonomy registered for reusable blocks.
Also, the admin bar at the top now contains a shortcut to create a new reusable block, just like it is possible to do for posts, media, pages or users.
As with every other content type, the admin menu on the left contains a dedicated sub-menu for reusable blocks, offering shortcuts
to see all existing reusable blocks, to create a new reusable block, and to see and manage categories, as well as any other publicly
available taxonomy registered for reusable blocks. Also, the admin bar at the top now contains a shortcut to create a new reusable
block, just like it is possible to do for posts,
media, pages or users.

#### Categories

Expand All @@ -59,20 +65,19 @@ However, this can be changed, without affecting the post's categories.

#### Search

In addition to the Category filter, the block picker also provides a search field.
The search query is used to find reusable blocks with either a matching title or content, or both.
Search results are sorted based on a smart algorithm using different weights for title matches vs. content matches, and exact matches vs. partial matches.
As a result, more relevant blocks are displayed first.
In addition to the Category filter, the block picker also provides a search field. The search query is used to find reusable blocks
with either a matching title or content, or both. Search results are sorted based on a smart algorithm using different weights for
title matches vs. content matches, and exact matches vs. partial matches. As a result, more relevant blocks are displayed first.

The search input also supports numeric ID lookups.
By entering a block ID, the result set will be just that one according block, ready to be inserted.
If the provided ID is a post ID, the results will be all reusable blocks referenced by that post, if any.
The search input also supports looking up numeric IDs. By entering a block ID, the result set will be just that one according block,
ready to be inserted. If the provided ID is a post ID, the results will be all reusable blocks referenced by that post, if any.

### PHP Filters

#### `altis_post_types_with_reusable_blocks`

This filter allows the user to manipulate the post types that can use reusable blocks and should have the relationship for the shadow taxonomy.
This filter allows the user to manipulate the post types that can use reusable blocks and should have the relationship for the
shadow taxonomy.

**Arguments:**

Expand All @@ -84,9 +89,9 @@ This filter allows the user to manipulate the post types that can use reusable b
// Add the "page" post type.
add_filter( 'altis_post_types_with_reusable_blocks', function ( aray $post_types ): array {

$post_types[] = 'page';
$post_types[] = 'page';

return $post_types;
return $post_types;
} );
```

Expand All @@ -104,14 +109,14 @@ This filter allows the user to modify the schema for the relationship data befor
// Add the post author to the schema.
add_filter( 'rest_get_relationship_item_additional_fields_schema', function ( array $additional_fields ): array {

$additional_fields['author'] = [
'description' => __( 'User ID for the author of the post.' ),
'type' => 'integer',
'context' => [ 'view' ],
'readonly' => true,
];
$additional_fields['author'] = [
'description' => __( 'User ID for the author of the post.' ),
'type' => 'integer',
'context' => [ 'view' ],
'readonly' => true,
];

return $additional_fields;
return $additional_fields;
} );
```

Expand All @@ -131,8 +136,8 @@ This filter allows the user to modify the relationship data right before it is r
// Add the post author to the REST response.
add_filter( 'rest_prepare_relationships_response', function ( WP_REST_Response $response, WP_Post $post ): WP_REST_Response {

$response->data['author'] = $post->post_author;
$response->data['author'] = $post->post_author;

return $response;
return $response;
}, 10, 2 );
```
84 changes: 49 additions & 35 deletions docs/branding.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,80 +4,94 @@ It's a common task to apply custom branding to match the site to various parts o

## Login screen

You can change the logo shown on the CMS login screen using the `login-logo` configuration option to provide a project root relative path to an image file.
You can change the logo shown on the CMS login screen using the `login-logo` configuration option to provide a project root relative
path to an image file.

```json
{
"extra": {
"altis": {
"modules": {
"cms": {
"login-logo": "/content/site-logo.svg"
}
}
}
}
"extra": {
"altis": {
"modules": {
"cms": {
"login-logo": "/content/site-logo.svg"
}
}
}
}
}
```

## Custom Admin Colour Scheme

If the default colour scheme does not meet the accessibility needs of your staff you can register custom schemes to provide high contrast alternatives. To register a custom admin colour scheme add the following function on the `admin_init` action.
If the default colour scheme does not meet the accessibility needs of your staff you can register custom schemes to provide high
contrast alternatives. To register a custom admin colour scheme add the following function on the `admin_init` action.

```php
wp_admin_css_color( string $key, string $name, string $url, array $colors = [], array $icons = [] );
```

NB: note the American spelling of `color` in the function name.

<!-- vale proselint.Spelling = NO -->

- `key`: The unique key for this theme.
- `name`: The name of the theme.
- `url`: The URL of the CSS file containing the colour scheme.
- `colors`: An array of CSS colour definition strings (hexadecimal format) which are used to give the user a feel for the theme. These colours are displayed in admin Users > Your Profile > Admin Color Scheme (if there are more than one available).
- `colors`: An array of CSS colour definition strings (hexadecimal format) which are used to give the user a feel for the theme.
These colours are displayed in admin Users > Your Profile > Admin Color Scheme (if there are more than one available).
- `icons`: CSS colour definitions (hexadecimal format) used to colour any SVG icons.
- `base`: SVG icon base colour, in hexadecimal format.
- `focus`: SVG icon colour on focus, in hexadecimal format.
- `current`: SVG icon colour of current admin menu link, in hexadecimal format.

<!-- vale proselint.Spelling = YES -->

Example:

```php
add_action( 'admin_init', 'add_colour_scheme' );
function add_colour_scheme() {
wp_admin_css_color(
'dusk',
_x( 'Dusk', 'admin colour scheme' ),
admin_url( "path/to/css/file/dusk.css" ),
[ '#25282b', '#363b3f', '#69a8bb', '#e14d43' ],
[
'base' => '#f1f2f3',
'focus' => '#fff',
'current' => '#fff',
]
);
wp_admin_css_color(
'dusk',
_x( 'Dusk', 'admin colour scheme' ),
admin_url( "path/to/css/file/dusk.css" ),
[ '#25282b', '#363b3f', '#69a8bb', '#e14d43' ],
[
'base' => '#f1f2f3',
'focus' => '#fff',
'current' => '#fff',
]
);
}
```

## Custom Favicon
The favicon shown for the application can be set using either the CMS or a configuration option. Using the CMS option will override the configuration option.
## Custom `favicon`

The favicon shown for the application can be set using either the CMS or a configuration option. Using the CMS option will override
the configuration option.

### CMS Option

1. Login to the admin area
2. Go to **Appearance** > **Customize** and click on the **Site Identity** tab
3. Scroll to **Site Icon** and click on the select site icon button, then upload the image you want to use as the icon.
4. Make any adjustments needed to the image if it's too large.
5. Publish your changes.

### Configuration Option

You can use the `favicon` configuration option to provide a project root relative path to an image file.

```json
{
"extra": {
"altis": {
"modules": {
"cms": {
"favicon": "/content/favicon.png"
}
}
}
}
"extra": {
"altis": {
"modules": {
"cms": {
"favicon": "/content/favicon.png"
}
}
}
}
}
```
```
Loading

0 comments on commit c84429f

Please sign in to comment.