diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..bc79ac9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,16 @@ +# Contributing + +## Running locally +Start local site with: + +```shell +wp-env start +``` + +Change permalink structure: + +```shell +wp-env run cli "wp rewrite structure '/%postname%'" +``` + +The site is now available at http://localhost:8888. diff --git a/README.md b/README.md index bf60fbe..8c3e909 100644 --- a/README.md +++ b/README.md @@ -65,17 +65,47 @@ function oidc_clients() { } ``` -## Development -Start local site with: +## Overriding templates +The pages provided by this plugin are rendered using templates. If you so wish, you can use your own templates instead of this plugins's [default templates](templates). + +To do so, you should create an `openid-connect/` directory under your theme, containing only the templates you wish to override. For example, if you wanted to override `authenticate/main.php` and `authenticate/forbidden.php` you would create them under an `openid-connect/` directory in your theme: ```shell -wp-env start +wp-content/themes/my-theme/ + │── openid-connect/ + │──── main.php + └──── forbidden.php ``` -Change permalink structure: +If your theme is a child theme, this plugin will first look for templates under the child theme, and then in the parent theme. If it doesn't find a template, it will fall back to using the default template. -```shell -wp-env run cli "wp rewrite structure '/%postname%'" +### Data +Templates are passed a single `$data` variable containing the values necessary to render said template. For example, you can access the name of the OIDC client as follows: + +```php +// wp-content/themes/my-theme/main.php + +/** @var stdClass $data **/ + +/** @var string $client_name The OIDC client name */ +$client_name = $data->client_name; +``` + +You can of course also call any other WordPress function, like you would in any other file in your theme. + +### Partials +In your templates, you can include partial templates (aka partials) by calling `$data->templates->partial()`: + +```php +// wp-content/themes/my-theme/main.php + +/** @var stdClass $data **/ + +/** @var \OpenIDConnectServer\Templating\Templating $templates */ +$templates = $data->templates; + +// Renders the
in the 'authenticate/form.php' partial. +$templates->partial( 'authenticate/form' ) ``` -The site is now available at http://localhost:8888. +Partials are also passed the `$data` variable.