From fb220dc7d1df38141c08c9b4edd63b502214010d Mon Sep 17 00:00:00 2001 From: "Eric Richer eric.richer@vistoconsulting.com" Date: Thu, 11 Apr 2024 13:43:32 -0400 Subject: [PATCH] Moved LmcMail to LmcMail repo. Updated home page. --- docs/{lmc-mail/Introduction.md => LmcMail.md} | 10 +- docs/lmc-mail/Configuration.md | 47 -------- docs/lmc-mail/Installation.md | 16 --- docs/lmc-mail/Usage.md | 73 ----------- docs/lmc-mail/_category_.json | 8 -- docs/lmc-mail/advanced-customization.md | 73 ----------- docusaurus.config.js | 9 +- sidebars.js | 6 +- src/components/HomepageFeatures/index.js | 114 +++++++++++++++++- .../HomepageFeatures/styles.module.css | 6 + src/pages/index.js | 2 +- 11 files changed, 130 insertions(+), 234 deletions(-) rename docs/{lmc-mail/Introduction.md => LmcMail.md} (67%) delete mode 100644 docs/lmc-mail/Configuration.md delete mode 100644 docs/lmc-mail/Installation.md delete mode 100644 docs/lmc-mail/Usage.md delete mode 100644 docs/lmc-mail/_category_.json delete mode 100644 docs/lmc-mail/advanced-customization.md diff --git a/docs/lmc-mail/Introduction.md b/docs/LmcMail.md similarity index 67% rename from docs/lmc-mail/Introduction.md rename to docs/LmcMail.md index 9af8bcd..8393b45 100644 --- a/docs/lmc-mail/Introduction.md +++ b/docs/LmcMail.md @@ -1,13 +1,7 @@ --- -sidebar_position: 1 +sidebar_position: 4 --- - LmcMail is an email service module that provides the ability to use the View Manager of a Laminas MVC application and the installed View Helper plugins to render HTML emails. - -## Requirements - -- PHP 8.1 or higher -- Laminas View -- Laminas Mail +[Documentation](https://lm-commons.github.io/LmcMail) \ No newline at end of file diff --git a/docs/lmc-mail/Configuration.md b/docs/lmc-mail/Configuration.md deleted file mode 100644 index d6b8bcb..0000000 --- a/docs/lmc-mail/Configuration.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -sidebar_position: 3 ---- -LmcMail supports the Laminas SMTP Mail Transport or the Laminas File Mail Transport and this is configured by the `transport` config key in the `lmcmail.local.php` file: - -```php title="/config/autoload/lmcmail.local.php" - [ - 'from' => [ - 'email' => 'user@example.com', - 'name' => 'User', - ], - - // For SMTP - 'transport' => [ - 'type' => 'smtp', - 'options' => [ - 'host' => 'example.com', - 'connection_class' => 'plain', - 'connection_config' => [ - 'ssl' => 'tls', - 'username' => 'user@example.com', - 'password' => 'somepassword', - ], - 'port' => 587, - ], - ] - // OR - - 'transport' => [ - 'type' => 'file', - 'options' => [ - 'path' => '/path/to/email/folder', - ], - ], - ], -]; -``` -In a production environment, an SMTP Mail Transport will more likely be used. - -In a development environment, it is typical to use a File Mail Transport to write message to files to validate the -rendered output. - -The `'transport'` configuration must comply with the `Laminas\Mail\Transport\Factory\Factory::create` method. - -The `'from'` configuration defines a default *from* address. The *from* address can also be specified at message creation. diff --git a/docs/lmc-mail/Installation.md b/docs/lmc-mail/Installation.md deleted file mode 100644 index baac904..0000000 --- a/docs/lmc-mail/Installation.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_position: 2 ---- - -Install the module via Composer: - -````shell -$ composer require lm-commons/lmc-mail -```` - -Composer will inject the module into the modules configuration, or you can add it manually to the `modules.config.php` or -`application.config.php`. - -Customize the module by copying and renaming the sample configuration file `lm-commons/lmc-mail/config/lmcmail.local.php.dist` to the application's -`config/autoload`. - diff --git a/docs/lmc-mail/Usage.md b/docs/lmc-mail/Usage.md deleted file mode 100644 index 3f1ca99..0000000 --- a/docs/lmc-mail/Usage.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -sidebar_position: 4 ---- -The Mail service can be retrieved from the service manager: - -```php -$messageService = $serviceManager->get(LmcMail\Service\MessageService::class); -``` - -Basic example to send an HTML email: - -```php -$viewModel = new \Laminas\View\Model\ViewModel(); -$viewModel->setTemplate('mail/html'); -$message = $messageService->createHtmlMessage( - ['email' => 'john@example.com', 'name' => 'John'], //from - ['email' => 'jane@example.com', 'name' => 'Jane'] //to - "This is the subject line, //subject - $viewModel); // View model - -$messageService->send($message); -``` - -The `'mail/html'` template must exist in the application's view template map. The HTML mail renderer will use -a layout template aliased as `'mail/layout'` in the view template map. This is defined in the `module.config.php` file. - -## Available methods - -### createHtmlMessage - -````php - /** - * Create an HTML message - * @param string|Address|AddressInterface|array|AddressList|Traversable $from - * @param string|Address|AddressInterface|array|AddressList|Traversable $to - * @param string $subject - * @param string|ModelInterface $nameOrModel - * @return Message - */ -createHtmlMessage(string|Address|AddressInterface|array|AddressList|Traversable $from, - string|Address|AddressInterface|array|AddressList|Traversable $to, - string $subject, - string|ModelInterface $nameOrModel): \Laminas\Mime\Message::class -```` -If `$nameorModel` is a string, it must correspond to the view template to use. - - -### createTextMessage -````php -/** - * Create a text message - * @param string|Address|AddressInterface|array|AddressList|Traversable $from - * @param string|Address|AddressInterface|array|AddressList|Traversable $to - * @param string $subject - * @param string|ModelInterface $nameOrModel - * @return Message - */ -createTextMessage(string|Address|AddressInterface|array|AddressList|Traversable $from, - string|Address|AddressInterface|array|AddressList|Traversable $to, - string $subject, - ModelInterface $nameOrModel): \Laminas\Mail\Message::class -```` -If `$nameorModel` is a string, it must correspond to the view template to use. - -### send -````php -/** - * Send the message - * @param Message $message - */ -send(Message $message): void -```` -where `$message` can be any object of type `\Laminas\Mail\Message` not necessarily one created by the above methods. diff --git a/docs/lmc-mail/_category_.json b/docs/lmc-mail/_category_.json deleted file mode 100644 index ea43019..0000000 --- a/docs/lmc-mail/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "LmcMail", - "position": 6, - "link": { - "type": "generated-index", - "description": "Wrapper for Laminas Mail that uses View Model to compose the email body" - } -} diff --git a/docs/lmc-mail/advanced-customization.md b/docs/lmc-mail/advanced-customization.md deleted file mode 100644 index d8efc68..0000000 --- a/docs/lmc-mail/advanced-customization.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -sidebar_position: 5 -title: Advanced Configuration ---- -LmcMail can be customized to the applications needs. - -#### Using view templates - -LmcMail uses nested view models to render the body of HTML messages. - -In a similar fashion to the view model structure of the Laminas MVC Skeleton, -the body is rendered using a layout view model to which the view model parameter (`$nameOrModel`) to the -`createHtmlMessage` method is added a child. -The rendered output of the `$nameOrModel` view model is captured in the variable `message` which is passed to the layout view model. - -A default template `'mail/layout'` is supplied in `lm-commons/lmc-mail/view/layout/layout.phtml`. This template can be -the starting point for your own layout template. -The layout template can be set using the `setLayoutTemplate()` method. Alternatively, -the `'mail/layout'` entry in the View Manager template map can be overridden to point to your template. Another -alternative is to use a factory delegator to the `MessageServiceFactory::class` to set the layout template after the -Message Service is created. - -View Helpers can be used when rendering view models. A common use case is to use `$this->url()` to render a link to your -application. - -#### Use alternate View Resolved and View Helper Manager - -LmcMail uses Service Manager aliases to get the View Resolver and View Helper Manager which resolves to the -Laminas MVC View resolver and manager. This allows to use any view template and helpers already defined in the application. - -````php -'aliases' => [ - // These aliases are used by the MailViewRendererFactory - // by default, they resolve to the Laminas MVC View Helper manager and Resolver - 'lmc_mail_view_helper_manager' => 'ViewHelperManager', - 'lmc_mail_view_resolver' => 'ViewResolver', -], -```` -If you want to use a different resolver and view helper manager, then update the aliases to point to your classes: - -````php -'aliases' => [ - 'lmc_mail_view_helper_manager' => 'MyHelperManager', - 'lmc_mail_view_resolver' => 'MyViewResolver', -], -```` - -If you want to use your own renderer, then you can override the Service Manager factory: -````php -'factories' => [ - // Override the factory with your own - 'lmc_mail_view_renderer' => MyViewRendererFactory::class, - /* ... */ -], -```` - -### Event Listening - -`MessageService::send()` triggers two events: - -- `MessageEvent::SEND` is triggered right before the message is sent by the transport service. -- `MessageEvent::SEND_POST` is triggered right after the message has been sent by the transport service. - -A listener to these events will receive an event of class `LmcMail\Service\MessageEvent` that extends the `\Laminas\EventManager\Event` -class with: - -- A `$message` property containing the message. The message is also stored in an event parameter named 'message'. -- A `getMessage()` method to get the `$message` property. -- A `setMessage(Message $message)` method to set the `$message` property and the corresponding event parameters. - -The `MessageService::send()` method, after triggering the `MessageEvent::SEND` event, will retrieve the message from the event and pass it to the transport service. This allows for the listener to modify the message if needed. - -A typical use case for listening to the send events would be to log that a message was sent. diff --git a/docusaurus.config.js b/docusaurus.config.js index 5ffca65..281a8c0 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -93,6 +93,10 @@ const config = { href: 'https://lm-commons.github.io/LmcRbacMvc/', label: 'LmcRbacMvc' }, + { + href: 'https://lm-commons.github.io/LmcMail/', + label: 'LmcMail' + }, ] }, { @@ -105,6 +109,7 @@ const config = { footer: { style: 'dark', links: [ + /* { title: 'Packages', items: [ @@ -126,7 +131,7 @@ const config = { }, { label: 'LmcMail', - to: '/docs/lmc-mail/Introduction', + to: 'https://lm-commons.github.io/LmcMail/', }, { label: 'LmcAdmin', @@ -134,6 +139,8 @@ const config = { }, ], }, + + */ { title: 'Community', items: [ diff --git a/sidebars.js b/sidebars.js index a6f855a..413a89a 100644 --- a/sidebars.js +++ b/sidebars.js @@ -15,11 +15,11 @@ const sidebars = { // By default, Docusaurus generates a sidebar from the docs folder structure mainSidebar: [{type: 'autogenerated', dirName: '.'}], - lmcRbacMvc: [{type: 'autogenerated', dirName: 'lmc-rbac-mvc'}], +// lmcRbacMvc: [{type: 'autogenerated', dirName: 'lmc-rbac-mvc'}], lmcUser: [{type: 'autogenerated', dirName: 'lmc-user'}], - lmcCors: [{type: 'autogenerated', dirName: 'lmc-cors'}], +// lmcCors: [{type: 'autogenerated', dirName: 'lmc-cors'}], lmcRbac: [{type: 'autogenerated', dirName: 'lmc-rbac'}], - lmcMail: [{type: 'autogenerated', dirName: 'lmc-mail'}], +// lmcMail: [{type: 'autogenerated', dirName: 'lmc-mail'}], // But you can create a sidebar manually /* diff --git a/src/components/HomepageFeatures/index.js b/src/components/HomepageFeatures/index.js index d3d18a1..ced1749 100644 --- a/src/components/HomepageFeatures/index.js +++ b/src/components/HomepageFeatures/index.js @@ -1,7 +1,70 @@ import clsx from 'clsx'; import Heading from '@theme/Heading'; import styles from './styles.module.css'; +import Link from '@docusaurus/Link'; +const PackageList = [ + { + title: 'LmcUser', + description: ( + <> + LmcUser is a user registration and authentication module for Laminas. LmcUser provides the foundations for + adding user authentication and registration to your Laminas site. It is designed to be very simple and easy + to extend. + + ), + href: 'https://lm-commons.github.io/LmcUser/', + }, + { + title: 'LmcCors', + description: ( + <> + LmcCors is a simple Laminas MVC module that helps you to deal with Cross-Origin Resource Sharing (CORS). + + ), + href: 'https://lm-commons.github.io/LmcCors/', + }, + { + title: 'LmcRbacMvc', + description: ( + <> + LmcRbacMvc is a role-based access control Laminas MVC module to provide additional + features on top of Laminas\Permissions\Rbac + + ), + href: 'https://lm-commons.github.io/LmcRbacMvc/', + }, + { + title: 'LmcMail', + description: ( + <> + LmcMail is an email service module that provides the ability to use the View Manager of a Laminas MVC + application and the installed View Helper plugins to render HTML emails. + + ), + href: 'https://lm-commons.github.io/LmcMail/', + }, + { + title: 'LmcRbac', + description: ( + <> + Role-based access control module to provide additional features on top of Zend\Permissions\Rbac + + ), + href: '/docs/lmc-rbac/introduction', + }, + { + title: 'LmcAdmin', + description: ( + <> + LmcAdmin Module for Laminas Framework + + ), + href: '/docs/lmc-admin/introduction', + }, +]; + +/* const FeatureList = [ { title: 'Easy to Use', @@ -35,6 +98,9 @@ const FeatureList = [ }, ]; + */ + +/* function Feature({Svg, title, description}) { return (
@@ -48,17 +114,57 @@ function Feature({Svg, title, description}) {
); } +*/ + +function Package({title, description, href}) { + return ( +
+
+ {title} +

{description}

+
+
+ + Documentation + +
+
+ ); +} + +function PackageCard({title, description, href}) { + return ( +
+
+
+ {title} +
+
+

+ {description} +

+
+
+
+ Documentation +
+
+
+
+ ); +} export default function HomepageFeatures() { return (
- {FeatureList.map((props, idx) => ( + {PackageList.map((props, idx) => ( <> - {/*} - - {*/} + + + ))}
diff --git a/src/components/HomepageFeatures/styles.module.css b/src/components/HomepageFeatures/styles.module.css index b248eb2..f8726e4 100644 --- a/src/components/HomepageFeatures/styles.module.css +++ b/src/components/HomepageFeatures/styles.module.css @@ -9,3 +9,9 @@ height: 200px; width: 200px; } + +.buttons { + display: flex; + align-items: center; + justify-content: center; +} diff --git a/src/pages/index.js b/src/pages/index.js index 5589ae2..fe4f96b 100644 --- a/src/pages/index.js +++ b/src/pages/index.js @@ -1,5 +1,5 @@ import clsx from 'clsx'; -import Link from '@docusaurus/Link'; +//import Link from '@docusaurus/Link'; import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; import Layout from '@theme/Layout'; import HomepageFeatures from '@site/src/components/HomepageFeatures';