Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

DOC-2420: Port changes from 7x docs for re-write of editor-plugin-verson.adoc #3301

Merged
merged 4 commits into from
May 21, 2024
Merged

DOC-2420: Port changes from 7x docs for re-write of editor-plugin-verson.adoc #3301

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
990dc3c
DOC-2420: Port changes from 7x docs for re-write of editor-plugin-ver…
kemister85 May 16, 2024
3a8b195
Update modules/ROOT/pages/editor-plugin-version.adoc
kemister85 May 21, 2024
afed5d3
Update modules/ROOT/nav.adoc
kemister85 May 21, 2024
782abab
Update modules/ROOT/pages/editor-plugin-version.adoc
kemister85 May 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion modules/ROOT/nav.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@
** xref:cloud-deployment-guide.adoc[Cloud deployment guide]
*** xref:editor-and-features.adoc[Cloud deployment of editor & plugins]
*** xref:features-only.adoc[Cloud deployment of plugins Only]
*** xref:editor-plugin-version.adoc[Specify editor & plugin versions]
*** xref:editor-plugin-version.adoc[Specify editor version & plugins]
*** xref:plugin-editor-version-compatibility.adoc[Version compatibility reference]
*** xref:cloud-troubleshooting.adoc[Cloud Troubleshooting]
** Premium server-side services guide
Expand Down
4 changes: 2 additions & 2 deletions modules/ROOT/pages/cloud-deployment-guide.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,9 @@ Connect to Tiny Cloud within a hybrid deployment.

|
[.lead]
xref:editor-plugin-version.adoc[Specify editor & plugin versions]
xref:editor-plugin-version.adoc[Specify editor & plugins]

Specifying editor and plugin versions for Tiny Cloud deployments.
Specifying editor and plugins for Tiny Cloud deployments.

|
[.lead]
Expand Down
176 changes: 70 additions & 106 deletions modules/ROOT/pages/editor-plugin-version.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,162 +1,126 @@
= Specify editor & plugin versions
:description_short: Specifying editor and plugin versions for Tiny Cloud deployments.
:description: Specifying editor and plugin versions for Tiny Cloud deployments.
= Specify editor version & plugins
:description_short: Specifying editor version and plugins for {cloudname} deployments.
:description: Instructions on setting the {productname} editor version and plugins for {cloudname} deployments.
:keywords: tinymce, cloud, script, textarea, apiKey, hybrid

[[specifying-the-tinymce-editor-version-deployed-from-cloud]]
== Specifying the TinyMCE editor version deployed from Cloud
== Specifying the {productname} editor version from {cloudname}

Use the URL provided to specify the {productname} version when deploying via {cloudname}. Refer to the xref:editor-and-features.adoc[{productname} editor via the {cloudname}] for more information.

The following example is the default for loading {productname} {productmajorversion} via {cloudname}. Substitute 'no-api-key' with your api key in the examples below.
To set the {productname} version when deploying from {cloudname}, use the following URL:

[source,html,subs="attributes+"]
----
<script src="{cdnurl}" referrerpolicy="origin"></script>
----

This URL specifies the latest and quality assured release of {productname}.
The example above shows the default way to load {productname} {productmajorversion} from {cloudname}. This URL ensures the most recent and verified version of {productname} is used.

=== Selecting specific version numbers
[TIP]
Replace 'no-api-key' with your own API key.

NOTE: All {cloudname} channels are based on the {enterpriseversion} version. For information on the latest version of the {cloudname} `{productmajorversion}` release channel, see: xref:release-notes.adoc[{productname} Release Notes]. For a list of changes that *may* be present in the {cloudname} testing channel, see: xref:changelog.adoc[{productname} Changelog].
For more details, check out the xref:editor-and-features.adoc[{productname} editor via {cloudname}].

[#{productmajorversion}-{productmajorversion}-testing-and-{productmajorversion}-dev-release-channels]
=== {productmajorversion}, {productmajorversion}-testing, and {productmajorversion}-dev release channels
[[specifying-the-cloud-deployment-of-plugins]]
== Specifying the Cloud Deployment of Plugins

Choose from the `{productmajorversion}`, `{productmajorversion}-testing`, or `{productmajorversion}-dev` release channels to load the latest version of {productname} from {cloudname}.
When self-hosting {productname}, integrators have the choice to host premium plugins or load them from {companyname} Cloud (a.k.a. hybrid mode). Depending on your requirements, you can use a combination of both approaches.

These channels are updated automatically and provide the latest {productname} version that matches the criteria below.
include::partial$misc/admon-script-tag-placement.adoc[]

[#{productmajorversion}-release-channel]
==== {productmajorversion} release channel
{companyname} offers the following configuration scripts to assist:

This channel deploys the latest release of {productname} that has passed our quality assurance process. The current version of {productname} available through the `/{productmajorversion}` channel can be found on the https://cdn.tiny.cloud/1/no-api-key/tinymce/{productmajorversion}/version.txt[{cloudname} {productname} {productmajorversion} version page]. The {productname} {productmajorversion} channel can be loaded from `{cdnurl}`.
=== `plugin.min.js` Standalone with No Exclusions.

[#example-using-the-{productmajorversion}-release-channel]
===== Example: using the `{productmajorversion}` release channel
The `plugins.min.js` script loads every premium plugin the API key is entitled to from the CDN.

[source,html,subs="attributes+"]
----
<script src="{cdnurl}" referrerpolicy="origin"></script>
<script src="https://cdn.tiny.cloud/1/api-key/tinymce/6/plugins.min.js" referrerpolicy="origin"></script>
----

[#{productmajorversion}-testing-release-channel]
==== {productmajorversion}-testing release channel

This channel deploys the current *release candidate* for the `{productmajorversion}` channel. The {productname} release candidate is undergoing quality assurance. The current version of {productname} available through the `{productmajorversion}-testing` channel can be found on the https://cdn.tiny.cloud/1/no-api-key/tinymce/{productmajorversion}-testing/version.txt[{cloudname} {productname} {productmajorversion}-testing version page].
=== `plugins.min.js` with Exclusions for Specific Plugins.

[#example-using-the-{productmajorversion}-testing-release-channel]
===== Example: using the `{productmajorversion}-testing` release channel
To exclude specific premium plugins from `plugins.min.js` because you are self-hosting them, add the excluded plugins to the script query parameters as shown below:

[source,html,subs="attributes+"]
----
<script src="https://cdn.tiny.cloud/1/no-api-key/tinymce/{productmajorversion}-testing/tinymce.min.js" referrerpolicy="origin"></script>
<script src="https://cdn.tiny.cloud/1/api-key/tinymce/6/plugins.min.js?mentions=sdk&powerpaste=sdk" referrerpolicy="origin"></script>
----

[#{productmajorversion}-dev-release-channel]
==== {productmajorversion}-dev release channel
[NOTE]
====
Ensure that the excluded plugins' names are appended with `=sdk`, such as `mentions=sdk`.
When {companyname} Cloud releases a new premium plugin, if you wish to self-host it this script tag will need to be updated to exclude it.
====

This channel deploys nightly builds of {productname}. This channel includes the unreleased changes documented in the https://github.com/tinymce/tinymce/blob/develop/modules/tinymce/CHANGELOG.md[{productname} changelog]. The current version of {productname} available through the `{productmajorversion}-dev` channel can be found on the https://cdn.tiny.cloud/1/no-api-key/tinymce/{productmajorversion}-dev/version.txt[{cloudname} {productname} {productmajorversion}-dev version page].
=== `cloud-plugins.min.js` for Specific Premium Plugins from {companyname} Cloud.

[#example-using-the-{productmajorversion}-dev-release-channel]
===== Example: using the `{productmajorversion}-dev` release channel
The `cloud-plugins.min.js` script allows loading of specific premium plugins from {companyname} Cloud.

[source,html,subs="attributes+"]
----
<script src="https://cdn.tiny.cloud/1/no-api-key/tinymce/{productmajorversion}-dev/tinymce.min.js" referrerpolicy="origin"></script>
<script src="https://cdn.tiny.cloud/1/api-key/tinymce/6/cloud-plugins.min.js?mentions&powerpaste&advcode" referrerpolicy="origin"></script>
----

== Specifying the version of premium plugins deployed from Tiny Cloud

Each {productname} version is bundled with a set of premium plugins, but it is possible to specify different versions of each premium plugin to use with {productname}. Use the URL query parameters to specify the version of each premium plugin to load. This approach works with both the xref:editor-and-features.adoc[{productname} editor and premium plugins deployment via {cloudname}] or just the xref:features-only.adoc[premium plugins deployment from {cloudname}].

The `+identifier+` of the plugin is used as a query parameter. This table summarises the possible options.

[cols=",,",options="header"]
|===
|Plugin |Identifier |Supported Versions
|xref:a11ychecker.adoc[Accessibility Checker] |`+a11ychecker+` |http://cdn.tiny.cloud/1/no-api-key/tinymce-plugins/a11ychecker/available-versions[Versions]
|xref:advcode.adoc[Advanced Code Editor] |`+advcode+` |http://cdn.tiny.cloud/1/no-api-key/tinymce-plugins/advcode/available-versions[Versions]
|xref:advtable.adoc[Advanced Tables] |`+advtable+` |http://cdn.tiny.cloud/1/no-api-key/tinymce-plugins/advtable/available-versions[Versions]
|xref:advanced-typography.adoc[Advanced Typography] |`+typography+` |http://cdn.tiny.cloud/1/no-api-key/tinymce-plugins/advtable/available-versions[Versions]
|xref:casechange.adoc[Case Change] |`+casechange+` |http://cdn.tiny.cloud/1/no-api-key/tinymce-plugins/casechange/available-versions[Versions]
|xref:checklist.adoc[Checklist] |`+checklist+` |http://cdn.tiny.cloud/1/no-api-key/tinymce-plugins/checklist/available-versions[Versions]
|xref:introduction-to-tiny-comments.adoc[Comments] |`+comments+` |http://cdn.tiny.cloud/1/no-api-key/tinymce-plugins/tinycomments/available-versions[Versions]
|xref:editimage.adoc[Enhanced Image Editing] |`+editimage+` |http://cdn.tiny.cloud/1/no-api-key/tinymce-plugins/editimage/available-versions[Versions]
|xref:introduction-to-mediaembed.adoc[Enhanced Media Embed] |`+mediaembed+` |http://cdn.tiny.cloud/1/no-api-key/tinymce-plugins/mediaembed/available-versions[Versions]
|xref:export.adoc[Export] |`+export+` |http://cdn.tiny.cloud/1/no-api-key/tinymce-plugins/export/available-versions[Versions]
|xref:footnotes.adoc[Footnotes] |`+footnotes+` |http://cdn.tiny.cloud/1/no-api-key/tinymce-plugins/footnotes/available-versions[Versions]
|xref:formatpainter.adoc[Format Painter] |`+formatpainter+` |http://cdn.tiny.cloud/1/no-api-key/tinymce-plugins/formatpainter/available-versions[Versions]
|xref:inline-css.adoc[Inline CSS] |`+inlinecss+` |http://cdn.tiny.cloud/1/no-api-key/tinymce-plugins/formatpainter/available-versions[Versions]
|xref:linkchecker.adoc[Link Checker] |`+linkchecker+` |http://cdn.tiny.cloud/1/no-api-key/tinymce-plugins/linkchecker/available-versions[Versions]
|xref:mentions.adoc[Mentions] |`+mentions+` |http://cdn.tiny.cloud/1/no-api-key/tinymce-plugins/mentions/available-versions[Versions]
|xref:mergetags.adoc[Merge Tags] |`+mergetags+` |http://cdn.tiny.cloud/1/no-api-key/tinymce-plugins/mergetags/available-versions[Versions]
|xref:pageembed.adoc[Page Embed] |`+pageembed+` |http://cdn.tiny.cloud/1/no-api-key/tinymce-plugins/pageembed/available-versions[Versions]
|xref:permanentpen.adoc[Permanent Pen] |`+permanentpen+` |http://cdn.tiny.cloud/1/no-api-key/tinymce-plugins/permanentpen/available-versions[Versions]
|xref:introduction-to-powerpaste.adoc[PowerPaste] |`+powerpaste+` |http://cdn.tiny.cloud/1/no-api-key/tinymce-plugins/powerpaste/available-versions[Versions]
|xref:rtc-getting-started.adoc[Real-Time Collaboration (RTC)] |`+rtc+` |http://cdn.tiny.cloud/1/no-api-key/tinymce-plugins/powerpaste/available-versions[Versions]
|xref:introduction-to-tiny-spellchecker.adoc[Spell Checker Pro] |`+tinymcespellchecker+` |http://cdn.tiny.cloud/1/no-api-key/tinymce-plugins/tinymcespellchecker/available-versions[Versions]
|xref:autocorrect.adoc[Spelling Autocorrect] |`+autocorrect+` |http://cdn.tiny.cloud/1/no-api-key/tinymce-plugins/autocorrect/available-versions[Versions]
|xref:tableofcontents.adoc[Table of Contents] |`+tableofcontents+`|http://cdn.tiny.cloud/1/no-api-key/tinymce-plugins/tableofcontents/available-versions[Versions]
|xref:tinydrive-introduction.adoc[Tiny Drive] |`+tinydrive+` |http://cdn.tiny.cloud/1/no-api-key/tinymce-plugins/tinydrive/available-versions[Versions]
|===

=== Specifying versions for the editor and premium plugin deployment

When deploying xref:editor-and-features.adoc[both the editor and premium plugins from {cloudname}], {productname} will load the premium plugins bundled with that version of the editor. To load a different version of a premium plugin, append the name of the plugin and the version to load as query parameters. The version must match one of the versions listed in the `+Supported Versions+` link for the relevant plugin.

Combine multiple plugin specifications using `+&+` in your query string. For example, to load:

* mentions v3.0
* powerpaste v6.0
* all other premium plugins from those bundled with `{productmajorversion}`

Append `+?mentions=3.0&powerpaste=6.0+`, such as:
[NOTE]
This approach is intended for edge cases where you self-host most premium plugins on your own servers and only need one or two from {companyname} Cloud.

[source,html,subs="attributes+"]
----
<script src="https://cdn.tiny.cloud/1/no-api-key/tinymce/{productmajorversion}/tinymce.min.js?mentions=3.0&powerpaste=6.0" referrerpolicy="origin"></script>
----
'''

=== Specifying a self-hosted deployment of features/plugins
=== Selecting Specific Editor Versions

When deploying xref:features-only.adoc[only premium plugins from {cloudname}], some features are served from {cloudname} and some features served from a self-hosted installation. There are two ways to achieve this: `+plugins.min.js+` and `+cloud-plugins.min.js+`.
[IMPORTANT]
====
All {cloudname} channels are based on the {enterpriseversion} version.
* For information on the latest version of the {cloudname} `{productmajorversion}` release channel, see: xref:release-notes.adoc[{productname} Release Notes].
* For a list of changes that *may* be present in the {cloudname} testing channel, see: xref:changelog.adoc[{productname} Changelog].
====

==== plugins.min.js
[#{productmajorversion}-{productmajorversion}-testing-and-{productmajorversion}-dev-release-channels]
=== Difference between using {productname} {productmajorversion}, {productmajorversion}-Testing, and {productmajorversion}-Dev release channels

Instead of loading `+tinymce.min.js+` from {cloudname}, serve {productname} from a self-hosted server, and load `+plugins.min.js+` from {cloudname}. {productname} which will attempt to load every *premium* plugin from {cloudname}, unless the version of the plugin is specified as the special version `+sdk+`. The query string for `+plugins.min.js+` works the same way as `+tinymce.min.js+`, except for the addition of `+sdk+`. For example, this script tag:
Choose from the `{productmajorversion}`, `{productmajorversion}-testing`, or `{productmajorversion}-dev` release channels to load the latest version of {productname} from {cloudname}.

The following example:
These channels are updated automatically and provide the latest {productname} version based on the following criteria:

* Assumes {productname} has already been loaded by another script on the page.
* Attempts to load `+mentions+` `+v3.0+` and `+powerpaste+` `+v6.0+` from {cloudname}.
* Attempts to load `+advcode+` from the self-hosted installation.
* Attempts to load all other premium plugins from those bundled with version `{productmajorversion}` of {productname}.
[#{productmajorversion}-release-channel]
==== {productmajorversion} Release Channel

This channel deploys the latest release of {productname} that has passed our quality assurance process. The current version of {productname} available through the `/{productmajorversion}` channel can be found on the https://cdn.tiny.cloud/1/no-api-key/tinymce/{productmajorversion}/version.txt[{cloudname} {productname} {productmajorversion} version page]. The {productname} {productmajorversion} channel can be loaded from `{cdnurl}`.

[#example-using-the-{productmajorversion}-release-channel]
===== Example: using the `{productmajorversion}` release channel

[source,html,subs="attributes+"]
----
<script src="https://cdn.tiny.cloud/1/no-api-key/tinymce/{productmajorversion}/plugins.min.js?mentions=3.0&powerpaste=6.0&advcode=sdk" referrerpolicy="origin"></script>
<script src="{cdnurl}" referrerpolicy="origin"></script>
----

The disadvantage of `+plugins.min.js+`: to load only one plugin from the {cloudname} and the rest from a self-hosted deployment, *ALL* other plugins need to be added as query parameter with the version as `+sdk+`. When {cloudname} releases a new plugin, this will need to be updated. In situations where most premium plugins need to be loaded from a self-hosted deployment, use `+cloud-plugins.min.js+`.
[#{productmajorversion}-testing-release-channel]
==== {productmajorversion}-Testing Release Channel

==== cloud-plugins.min.js
This channel deploys the current *release candidate* for the `{productmajorversion}` channel. The {productname} release candidate is undergoing quality assurance. The current version of {productname} available through the `{productmajorversion}-testing` channel can be found on the https://cdn.tiny.cloud/1/no-api-key/tinymce/{productmajorversion}-testing/version.txt[{cloudname} {productname} {productmajorversion}-testing version page].

Instead of loading `+tinymce.min.js+` from {cloudname}, serve {productname} from a self-hosted server, and load `+cloud-plugins.min.js+` from {cloudname}. Unlike `+plugins.min.js+`, `+cloud-plugins.min.js+` defaults to loading every *premium* plugin from the *self-hosted {productname} installation*, not {cloudname}. However, plugins can be loaded from {cloudname} by specifying them as query parameters.
[#example-using-the-{productmajorversion}-testing-release-channel]
===== Example: Using the `{productmajorversion}-testing` Release Channel

With `+cloud-plugins.min.js+`, the plugins listed in the query strings do not require a version. If there is no version specified, {productname} uses the version bundled with the {productname} version requested. There is also no need to specify `+sdk+` as the version for any plugin, as that is the default.
[source,html,subs="attributes+"]
----
<script src="https://cdn.tiny.cloud/1/no-api-key/tinymce/{productmajorversion}-testing/tinymce.min.js" referrerpolicy="origin"></script>
----

[#{productmajorversion}-dev-release-channel]
==== {productmajorversion}-Dev Release Channel

This channel deploys nightly builds of {productname}, which includes **unreleased changes** from the link:https://github.com/tinymce/tinymce/tree/main[{productname} repository^].

The following example:
The current version of {productname} is available on the `{productmajorversion}-dev` channel can be found on the link:https://cdn.tiny.cloud/1/no-api-key/tinymce/{productmajorversion}-dev/version.txt[{cloudname} {productname} {productmajorversion}-dev version page^].

* Assumes {productname} has already been loaded by another script on the page.
* Attempts to load `+mentions+` `+v3.0+` and `+powerpaste+` `+v6.0+` from {cloudname}.
* Attempts to load `+advcode+` from the version bundled with version `{productmajorversion}` of {productname} because it doesn't specify a version.
* Attempts to load all other premium plugins from the self-hosted installation.

[#example-using-the-{productmajorversion}-dev-release-channel]
===== Example: Using the `{productmajorversion}-dev` Release Channel

[source,html,subs="attributes+"]
----
<script src="https://cdn.tiny.cloud/1/no-api-key/tinymce/{productmajorversion}/cloud-plugins.min.js?mentions=3.0&powerpaste=6.0&advcode" referrerpolicy="origin"></script>
----

The disadvantage of `+cloud-plugins.min.js+`: every plugin to be loaded from {cloudname} must be added to the query parameter. When {cloudname} releases a new plugin, this will need to be updated. In situations where most premium plugins need to be loaded from {cloudname}, use `+plugins.min.js+`.
<script src="https://cdn.tiny.cloud/1/no-api-key/tinymce/{productmajorversion}-dev/tinymce.min.js" referrerpolicy="origin"></script>
----
Loading
Loading