diff --git a/README.md b/README.md index 247eeca..c53d490 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,10 @@ -## Twill Metadata +# Twill Metadata -This package is a simple way to add editable SEO metadata to your twill models. +This package is a simple way to add SEO metadata to your [Twill](https://twill.io/) models by providing a drop-in fieldset to add all the required fields into your model edit form. With sensible defaults, configurable fallbacks, and a global settings screen; this package should meet most of the needs for optimising meta tags within a site. -#### Installation +![default and expanded views of twill metadata fieldset](https://github.com/cwsdigital/twill-metadata/blob/master/Twill-Metadata-Preview.jpg) + +## Installation ```shell script $ composer require cwsdigital/twill-metadata ``` @@ -11,7 +13,9 @@ $ composer require cwsdigital/twill-metadata $ artisan migrate ``` -### In your model +## Configuration + +### In the model Set your model to use the `HasMetadata` trait, and add the public property `$metadataFallbacks`. Your model also need to use the HasMedias trait in order to allow for OpenGraph images. @@ -27,7 +31,7 @@ class Page extends Model { } ``` -### In your controller +### In the controller In the Twill admin controller for the model, ensure the `metadata_card_type_options` and `metadata_og_type_options` are set in the `formData()` method. ```php @@ -41,10 +45,10 @@ protected function formData($request) } ``` -### In your repository +### In the repository Add `use HandleMetadata` onto your page repository. ```php -//App/Repositories/PageRepository.php +// App/Repositories/PageRepository.php class PageRepository extends ModuleRepository { use HandleBlocks, HandleSlugs, HandleMedias, HandleFiles, HandleRevisions, HandleMetadata; @@ -56,8 +60,8 @@ class PageRepository extends ModuleRepository } ``` -### In your view - +### In the view +#### Add the fieldset to your form In the admin 'form.blade.php' view add the metadata fieldset to the additional fieldsets of the form. ```blade {{-- resources/views/admin/pages/form.blade.php --}} @@ -76,7 +80,7 @@ In the admin 'form.blade.php' view add the metadata fieldset to the additional f @stop ``` -### Add the global settings form +#### Add the global settings form In your twill-navigation config file add a settings section for the form fields. ```php // config/twill-navigation.php @@ -103,7 +107,7 @@ return [ ``` ```blade - +{{-- views/admin/settings/seo.blade.php --}} @extends('twill::layouts.settings') @section('contentFields') @@ -111,7 +115,40 @@ return [ @stop ``` -### Config & Customisation + +## Setting meta tags +In your controller for your front end application you can add the trait `SetsMetadata` and then use the `setMetadata()` function to set the metadata. + +```php +first(); + $this->setMetadata($page); + return view('site.pages.page', ['page' => $page ]); + } +} +``` + +Under the hood this uses the [artesaos/seotools](https://github.com/artesaos/seotools) package to set and display metadata. So you are free to not use the above helper, and manually set the meta tags as required. Or you can use the helper, and then use the methods provided by the package to amend the tags. + +## Outputting meta tags +See the documentation for [artesaos/seotools](https://github.com/artesaos/seotools) for more granular options, but the easiest way is shown below: +```blade +{{-- resources/views/layouts/site.blade.php --}} + + + + {!! SEO::generate() !!} + + +``` + +## Customization You can publish the config for the package with the following command: ```shell script @@ -132,6 +169,7 @@ Within the config file is a fallbacks array, which can be customised according t To provide different fallback configurations to different models with the HasMetadata trait you can use the same array in the public $metadataFallBacks property on the model. ```php +// App/Models/Page.php class Page extends Model { use HasMetadata; @@ -152,35 +190,3 @@ If you wish to provide a default OpenGraph Type and Twitter Card Type then you c public $metadataDefaultCardType = 'summary_large_image'; ``` -### Setting Meta Tags -In your controller for your front end application you can add the trait `SetsMetadata` and then use the `setMetadata()` function to set the metadata. - -```php -first(); - $this->setMetadata($page); - return view('site.pages.page', ['page' => $page ]); - } -} -``` - -Under the hood this uses the [artesaos/seotools](https://github.com/artesaos/seotools) package to set and display metadata. So you are free to not use the above helper, and manually set the meta tags as required. Or you can use the helper, and then use the methods provided by the package to amend the tags. - -### Outputting the meta tags -See the documentation for [artesaos/seotools](https://github.com/artesaos/seotools) for more granular options, but the easiest way is shown below: -```blade -{{-- resources/views/layouts/site.blade.php --}} - - - - {!! SEO::generate() !!} - - -``` -