#1627: Laravel integration docs (#2132)

* #1627: work in progress

* #1627: laravel docs work

* wip

* Draft procedures

* Completed Draft of Laravel integration docs

* fix component rendering tags

component rendering tags need to be kabab-case

_data/nav.yml

@@ -913,6 +913,12 @@
   - url: "bootstrap"
   - url: "django"
   - url: "jquery"
+  - url: "laravel"
+    pages:
+    - url: "laravel-introduction"
+    - url: "laravel-tiny-cloud"
+    - url: "laravel-composer-install"
+    - url: "laravel-zip-install"
   - url: "expressjs"
   - url: "rails"
     pages:

_includes/install/composer.md

@@ -1,7 +1,7 @@
-If you're using Composer package manager, add the following to `composer.json`.
+If you're using Composer package manager, run the following on a command line or command prompt:
 
-```
-php composer.phar require "tinymce/tinymce" ">= {{site.productmajorversion}}"
+```sh
+composer require tinymce/tinymce
 ```
 
 ### Step 1: Include the TinyMCE script

_includes/install/upgrading-info.md

@@ -35,7 +35,7 @@ $ npm install {{site.prodnamecode}}@latest --save
 #### Composer
 To upgrade to {{site.productname}} {{site.productminorversion}} using Composer, run:
 ```sh
-$ php composer.phar update "{{site.prodnamecode}}/{{site.prodnamecode}}"
+$ composer require tinymce/tinymce
 ```
 
 #### NuGet

_includes/integrations/angular-tech-ref.md

@@ -104,7 +104,7 @@ None of the configuration properties are **required** for `tinymce-angular` to w
 #### `apiKey`
 {{site.cloudname}} API key. Required for deployments using the {{site.cloudname}} to provide the {{site.productname}} editor.
 
-To register for a {{site.cloudname}} API key, visit the [sign-up page]({{site.accountsignup}}).
+{% include misc/get-an-api-key.md %}
 
 **Default value:** `no-api-key`
 

_includes/integrations/laravel-quick-start.md

@@ -0,0 +1,172 @@
+{% if productSource == "cloud" %}
+  {% assign scriptSource = site.cdnurl %}
+  {% assign packageSource = site.cloudname %}
+{% elsif productSource == "composer" %}
+  {% assign scriptSource = "{{ asset('js/tinymce/tinymce.min.js') }}" %}
+  {% assign packageSource = "[TinyMCE Composer package](https://packagist.org/packages/tinymce/tinymce)" %}
+{% else %}
+  {% assign scriptSource = "{{ asset('js/tinymce/tinymce.min.js') }}" %}
+  {% assign packageSource = "TinyMCE .zip package" %}
+{% endif %}
+
+This guide assists with adding {{site.productname}} from the {{packageSource}} to pages or views in Laravel. The example Laravel project created in this procedure is based on the Laravel project documented in the Laravel Docs, under [Installation Via Composer](https://laravel.com/docs/8.x/installation#installation-via-composer). The guide will create two blades: one for the JavaScript and another for the editor placeholder, to reflect how {{site.productname}} should be used in production environments.
+
+## Requirements
+
+This procedure assumes the following prerequisites have been installed:
+
+* [PHP](https://www.php.net/)
+* [Composer](https://getcomposer.org/){% if productSource != "cloud" %}
+* [Node.js](https://nodejs.org/)
+{% endif %}
+
+## Procedure
+
+1. On a command line (or command prompt), create a new Laravel project named `my-example-app` by running the following command:
+
+    ```sh
+    composer create-project laravel/laravel my-example-app
+    ```
+
+1. Change into the root directory of the Laravel application, such as:
+
+    ```sh
+    cd my-example-app
+    ```
+
+{% if productSource != "cloud" %}
+1. Install the required Node.js components, including [Laravel Mix](https://laravel.com/docs/8.x/mix):
+
+    ```sh
+    npm install
+    ```
+
+{% endif %}
+{% if productSource == "composer" %}
+1. Add {{site.productname}} to the project using Composer:
+
+    ```sh
+    composer require tinymce/tinymce
+    ```
+
+1. Add a Laravel Mix task to copy {{site.productname}} to the public files when Mix is run, such as:
+
+    _File:_ `webpack.mix.js`
+    ```js
+    mix.copyDirectory('vendor/tinymce/tinymce', 'public/js/tinymce');
+    ```
+
+{% endif %}
+{% if productSource == "zip" %}
+1. Download {{site.productname}}.
+
+    * For Self-hosted Enterprise customers, visit [{{site.companyname}} - Self-hosted releases]({{site.download-community}})
+    * For the self-hosted {{site.productname}} community edition, visit [{{site.accountpage}} - Downloads]({{site.download-enterprise}})
+
+1. Extract (or unzip) the downloaded {{site.productname}} `.zip` file into the `resources/js/` directory of the Laravel project, such as:
+
+    ```sh
+    unzip ../tinymce_latest.zip -d resources/js
+    ```
+
+1. Add a Laravel Mix task to copy {{site.productname}} to the public files when Mix is run, such as:
+
+    _File:_ `webpack.mix.js`
+    ```js
+    mix.copyDirectory('resources/js/tinymce/js/tinymce', 'public/js/tinymce');
+    ```
+
+{% endif %}
+{% if productSource != "cloud" %}
+1. Run Laravel Mix to copy {{site.productname}} to the `public/js/` directory:
+
+    ```sh
+    npx mix
+    ```
+
+{% endif %}
+1. Create a new reusable [component (`blade.php`)](https://laravel.com/docs/8.x/blade#components) for the {{site.productname}} configuration, such as:
+
+    ```sh
+    php artisan make:component Head/tinymceConfig
+    ```
+
+    This will create the blade `resources/views/components/head/tinymce-config.blade.php`.
+
+1. Open the newly created `.blade.php` file in a text editor and replace the contents with:
+
+    * The {{site.productname}} source script.
+    * A {{site.productname}} configuration.
+
+    For example:
+
+    _File:_ `resources/views/components/head/tinymce-config.blade.php`
+
+    ```html
+    <script src="{{ scriptSource }}" referrerpolicy="origin"></script>
+    <script>
+      tinymce.init({
+        selector: 'textarea#myeditorinstance', // Replace this CSS selector to match the placeholder element for TinyMCE
+        plugins: 'code table lists',
+        toolbar: 'undo redo | formatselect| bold italic | alignleft aligncenter alignright | indent outdent | bullist numlist | code | table'
+      });
+    </script>
+    ```
+
+{% if productSource == "cloud" %}
+1. Replace `no-api-key` in the {{site.productname}} source script with your {{site.cloudname}} API Key.
+
+    {% include misc/get-an-api-key.md %}
+{% endif %}
+
+1. Create a second blade containing a placeholder HTML element for {{site.productname}}, such as:
+
+    ```sh
+    php artisan make:component Forms/tinymceEditor
+    ```
+
+    This will create the blade `resources/views/components/forms/tinymce-editor.blade.php`.
+
+1. Open the newly created `.blade.php` file in a text editor and replace the contents with a placeholder, matching the CSS selector provided to the `selector` option in the editor configuration.
+
+    For example:
+
+    _File:_ `resources/views/components/forms/tinymce-editor.blade.php`
+
+    ```html
+    <form method="post">
+      <textarea id="myeditorinstance">Hello, World!</textarea>
+    </form>
+    ```
+
+1. Add the blade components on the pages or views where {{site.productname}} is needed. The configuration blade (`Head/tinymceConfig` in this example) can be added to the `<head>` or at the end of the `<body>` on the target page or view. The placeholder blade (`Forms/tinymceEditor`) should be added where {{site.productname}} is required on the page.
+
+    For example:
+
+    _File:_ `resources/views/welcome.blade.php`
+
+    ```html
+    <!DOCTYPE html>
+    <html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
+      <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <title>TinyMCE in Laravel</title>
+        <!-- Insert the blade containing the TinyMCE configuration and source script -->
+        <x-head.tinymce-config/>
+      </head>
+      <body>
+        <h1>TinyMCE in Laravel</h1>
+        <!-- Insert the blade containing the TinyMCE placeholder HTML element -->
+        <x-forms.tinymce-editor/>
+      </body>
+    </html>
+    ```
+
+1. Start the Laravel development server to verify that {{site.productname}} loads on the page or view, such as running the following command and opening the page on the localhost.
+
+    ```sh
+    php artisan serve
+    ```
+
+{% include misc/quickstart-next-steps.md %}

_includes/integrations/react-tech-ref.md

@@ -161,7 +161,7 @@ None of the configuration props are **required** for the {{site.productname}} Re
 
 Required for deployments using the {{site.cloudname}} to provide the {{site.productname}} editor without the warning message "This domain is not registered...".
 
-To register for a {{site.cloudname}} API key, visit the [sign-up page]({{site.accountsignup}}).
+{% include misc/get-an-api-key.md %}
 
 **Default value:** `no-api-key`
 

_includes/integrations/vue-tech-ref.md

@@ -102,7 +102,7 @@ None of the configuration properties are **required** for `tinymce-vue` to work.
 #### `api-key`
 {{site.cloudname}} API key. Required for deployments using the {{site.cloudname}} to provide the {{site.productname}} editor.
 
-To register for a {{site.cloudname}} API key, visit the [sign-up page]({{site.accountsignup}}).
+{% include misc/get-an-api-key.md %}
 
 **Default value:** `no-api-key`
 

_includes/misc/get-an-api-key.md

@@ -0,0 +1 @@
+To register for a {{site.cloudname}} API key, visit the [{{site.accountpage}} sign-up page]({{site.accountsignup}}). To retrieve the {{site.cloudname}} API key for an existing {{site.accountpage}}, login and visit the [{{site.accountpage}} Dashboard]({{site.accountpageurl}}).

_includes/misc/quickstart-next-steps.md

@@ -0,0 +1,11 @@
+## Next Steps
+For information on:
+
+* Customizing {{site.productname}}, see: [Basic Setup]({{site.baseurl}}/general-configuration-guide/basic-setup/).
+* The three editor modes, see:
+    * [{{site.productname}} classic editing mode]({{site.baseurl}}/general-configuration-guide/use-tinymce-classic/).
+    * [{{site.productname}} inline editing mode]({{site.baseurl}}/general-configuration-guide/use-tinymce-inline/).
+    * [{{site.productname}} distraction-free editing mode]({{site.baseurl}}/general-configuration-guide/use-tinymce-distraction-free/).
+* Adding {{site.productname}} plugins, see: [Work with plugins to extend TinyMCE]({{site.baseurl}}/general-configuration-guide/work-with-plugins/).
+* Localizing the {{site.productname}} editor, see: [Localize {{site.productname}}]({{site.baseurl}}/general-configuration-guide/localize-your-language/).
+* For information on the CSS required to render some {{site.productname}} elements outside of the editor, see: [Boilerplate content CSS]({{site.baseurl}}/general-configuration-guide/boilerplate-content-css/).

_includes/release-notes/overview.md

@@ -7,7 +7,7 @@ TinyMCE 5.0 has an ARIA [WCAG 2.1 standards](https://www.w3.org/WAI/standards-gu
 
 Include this line of code in the <head> of the HTML page and link to the tinymce.min.js source file. Substitute 'no-api-key' with your api key.
 
-```js
+```html
 <script src="{{ site.cdnurl }}" referrerpolicy="origin"></script>
 ```
 

cloud-deployment-guide/editor-and-features.md

@@ -20,7 +20,7 @@ Insert the {{site.productname}} editor code into the application to load {{site.
 
 The following example adds a script tag into the application that inserts the code. Use the `<head>` of the page on a web page. Be sure to substitute 'no-api-key' with your api key.
 
-```js
+```html
 <script src="{{ site.cdnurl }}" referrerpolicy="origin"></script>
 ```
 
@@ -33,7 +33,7 @@ The following example adds a script tag into the application that inserts the co
 
 <a class="anchor" id="referer-troubleshooting"></a>
 
-> **Important**: {{site.cloudname}} verifies the domain {{site.productname}} is loading from by checking the **Referer** header in the network request. Sometimes the domains in the **Referer** header does not match with the URL in the browser's address bar.  
+> **Important**: {{site.cloudname}} verifies the domain {{site.productname}} is loading from by checking the **Referer** header in the network request. Sometimes the domains in the **Referer** header does not match with the URL in the browser's address bar.
 >
 > To check the **Referer** header, open your browser's _Developer's Tools_ and open the _Network_ tab. From there, find the request being made to load {{site.productname}} with your API key, and click on the **Headers** tab.  In the section called **Request Headers** there should be a field for **Referer**. If the value there is different from one of your registered URLs, you may need to adjust either your registered URLs, or your application's **Refer** header settings.
 
@@ -96,7 +96,7 @@ Migrating from a self-hosted environment to {{site.cloudname}} is easy. Remove t
 
 Replace the script tag with the following:
 
-```js
+```html
 <script src="{{ site.cdnurl }}" referrerpolicy="origin"></script>
 ```
 

integrations/laravel/index.md

@@ -0,0 +1,21 @@
+---
+layout: default
+title: Using TinyMCE with the Laravel framework
+title_nav: Laravel
+description_short: A guide to using TinyMCE with the PHP-based Laravel framework.
+description: A guide to using TinyMCE with the PHP-based Laravel framework.
+type: folder
+---
+
+{% assign navigation = site.data.nav %}
+{% for entry in navigation %}
+  {% if entry.url == "integrations" %}
+    {% for subentry in entry.pages %}
+      {% if subentry.url == "laravel" %}
+        {% assign links = subentry.pages %}
+      {% endif %}
+    {% endfor %}
+  {% endif %}
+{% endfor %}
+
+{% include index.html links=links %}

integrations/laravel/laravel-composer-install.md

@@ -0,0 +1,11 @@
+---
+layout: default
+title: Using the TinyMCE composer package with the Laravel framework
+title_nav: Using the Composer package
+description: A guide on integrating the TinyMCE Composer package into the Laravel framework.
+keywords: integration integrate laravel php composer
+---
+
+{% assign productSource = "composer" %}
+
+{% include integrations/laravel-quick-start.md %}

integrations/laravel/laravel-introduction.md

@@ -0,0 +1,15 @@
+---
+layout: default
+title: Introduction to using TinyMCE with the Laravel framework
+title_nav: Introduction
+description: Overview of integrating TinyMCE into the Laravel framework.
+keywords: integration integrate laravel php composer
+---
+
+[Laravel](https://laravel.com/) is a scaleable web application framework built on PHP. The following guides provide procedures for creating a new Laravel project and adding {{site.productname}} to the project.
+
+These guides assist with adding {{site.productname}} to pages or views in Laravel. The example Laravel projects created in these procedures are based on the Laravel project documented in the Laravel Docs, under [Installation Via Composer](https://laravel.com/docs/8.x/installation#installation-via-composer). These guides will create two blades: one for the JavaScript and another for the editor placeholder, to reflect how {{site.productname}} should be used in production environments.
+
+* [Using TinyMCE from the Tiny Cloud CDN with the Laravel framework]({{site.baseurl}}/integrations/laravel/laravel-tiny-cloud/).
+* [Using the TinyMCE Composer package with the Laravel framework]({{site.baseurl}}/integrations/laravel/laravel-composer-install/).
+* [Using the TinyMCE .zip package with the Laravel framework]({{site.baseurl}}/integrations/laravel/laravel-zip-install/).

integrations/laravel/laravel-tiny-cloud.md

@@ -0,0 +1,11 @@
+---
+layout: default
+title: Using TinyMCE from the Tiny Cloud CDN with the Laravel framework
+title_nav: Using Tiny Cloud
+description: A guide on integrating TinyMCE from the Tiny Cloud into the Laravel framework.
+keywords: integration integrate laravel php composer
+---
+
+{% assign productSource = "cloud" %}
+
+{% include integrations/laravel-quick-start.md %}

integrations/laravel/laravel-zip-install.md

@@ -0,0 +1,11 @@
+---
+layout: default
+title: Using the TinyMCE .zip package with the Laravel framework
+title_nav: Using a .zip package
+description: A guide on integrating a .zip version of TinyMCE into the Laravel framework.
+keywords: integration integrate laravel php composer
+---
+
+{% assign productSource = "zip" %}
+
+{% include integrations/laravel-quick-start.md %}

quick-start.md

@@ -70,15 +70,5 @@ Process the content with a form handler.
 
 When the `<form>` is submitted, {{site.productname}} {{site.productmajorversion}} will `POST` the content in the same way as a normal HTML `<textarea>`, including the HTML elements and inline CSS of the editor content. The host's form handler can process the submitted content in the same way as content from a regular `<textarea>`.
 
-## Next Steps
-For information on:
-
-  * Customizing {{site.productname}}, see: [Basic Setup]({{site.baseurl}}/general-configuration-guide/basic-setup/).
-  * The three editor modes:
-    * [{{site.productname}} classic editing mode]({{site.baseurl}}/general-configuration-guide/use-tinymce-classic/).
-    * [{{site.productname}} inline editing mode]({{site.baseurl}}/general-configuration-guide/use-tinymce-inline/).
-    * [{{site.productname}} distraction-free editing mode]({{site.baseurl}}/general-configuration-guide/use-tinymce-distraction-free/).
-  * Adding {{site.productname}} plugins, see: [Work with plugins to extend TinyMCE]({{site.baseurl}}/general-configuration-guide/work-with-plugins/).
-  * Localizing the {{site.productname}} editor, see: [Localize {{site.productname}}]({{site.baseurl}}/general-configuration-guide/localize-your-language/).
-  * For information on the CSS required to render some {{site.productname}} elements outside of the editor, see: [Boilerplate content CSS]({{site.baseurl}}/general-configuration-guide/boilerplate-content-css/).
-  * Self-hosting {{site.productname}}, see: [Installing {{ site.productname }}]({{site.baseurl}}/general-configuration-guide/advanced-install/).
+{% include misc/quickstart-next-steps.md %}
+* Self-hosting {{site.productname}}, see: [Installing {{ site.productname }}]({{site.baseurl}}/general-configuration-guide/advanced-install/).