Differences

This shows you the differences between two versions of the page.

--- plugins [2021/10/01 09:21] – [How are plugins loaded] witsec
+++ plugins [2024/09/01 14:30] (current) – external edit 127.0.0.1
@@ Line 5: / Line 5: @@
 ==== How are plugins loaded ====
-Plugins are loaded through the `params.json` file. Depending on what your extension needs (and when), you can load one or more plugins. The most common way to tell Mobirise what plugins exist is to place them all in the same directory. In the example below, all plugins are in the same `plugins` directory:
+Plugins are loaded through the ''params.json'' file. Depending on what your extension needs (and when), you can load one or more plugins. The most common way to tell Mobirise what plugins exist is to place them all in the same directory. In the example below, all plugins are in the same `plugins` directory:
-<code json>"plugins": [
+<code javascript>
+"plugins": [
   "plugins"
-],</code>
+]
+</code>
-[this page is under construction]
+These few lines tell Mobirise that plugins can be found in the ''plugins'' folder.
+Having all plugins in the same directory does not get them loaded however. For that, you'll need to create a ''plugin.json'' file.
+==== plugin.json ====
+Each directory that contains one or more plugins should have a ''plugin.json'' file to actually load them into Mobirise. Here's a little example:
+<code javascript>
+[
+  {
+    "name": "plugin-name",
+    "priority": 3000,
+    "files": [
+      "plugin-name-or-directory/myscript.js"
+    ]
+  }
+]
+</code>
+Through this JSON code you're telling Mobirise what the name of the plugin is and what files should be loaded.
+=== name ===
+Make sure the ''name'' of your plugin is unique, so that it doesn't interfere with any other plugin. In the example above we've named it ''plugin-name''. If you have just one plugin for your extension, you may as well use the same name for the plugin as your extension.
+=== priority ===
+The ''priority'' tells Mobirise when to load the file(s). This is important when you want to make sure your plugin is loaded before or after other scripts, like jQuery or Bootstrap. A priority of 3000 or higher is likely to load somewhere near the end of the ''</body>'' tag, where a priority of 100 would make your plugin load as (one of) the first scripts. You'll have to play around with this value.
+=== files ===
+This is a list of one or more files you want to load or publish. Mobirise is smart enough to automatically place JavaScript files in the HTML. If you want to load images or other file types, Mobirise will simply publish them, without putting them in any HTML.
+Files don't **have** to be in their own folder, but especially if you have multiple files for a plugin, it's easier to manage them by placing them in their own folder.
+==== When will a plugin be loaded ====
+Good question. By following the steps above you've only told Mobirise this plugin exists, but this won't get it loaded straight away. Depending on what your extensions needs, there are various ways to load a plugin. Let's start with how most plugins get loaded.
+=== Section tag ===
+The most common way to load a plugin is when the ''section'' tag refers to a plugin. Here's how that's done:
+<code html>
+<section class="someClass" plugins="plugin-name">
+</code>
+That's it. Mobirise now knows you want to use this plugin in a block and will automatically do what its told to do through the ''plugin.json'' file. Go ahead and try it. When you publish your (test) website, check the source code of the HTML and you'll find your scripts are loaded at the bottom (if you're loading JavaScript files, that is).
+=== condition ===
+There's another way to get your plugin to load. For example when you want your script to be loaded at all times, without having to depend on any block to refer to it. You do this by adding a ''condition'' key to the ''plugin.json'' file. Here's an example:
+<code javascript>
+[
+  {
+    "name": "plugin-name",
+    "condition": true,
+    "priority": 3000,
+    "files": [
+      "plugin-name-or-directory/myscript.js"
+    ]
+  }
+]
+</code>
+If the condition is met, the plugin will be loaded. In this case you've set it to ''true'', so the plugin will always be loaded and you'll always find the ''myscript.js'' file referenced inside the HTML.
+It's also possible to have the plugin rely on a theme or parameter setting. For example, if your plugin should only be loaded if the "Animate on Scroll" is enabled, you could do something like this:
+<code javascript>
+[
+  {
+    "name": "plugin-name",
+    "condition": ["_theme.isAnimatedOnScroll"],
+    "priority": 3000,
+    "files": [
+      "plugin-name-or-directory/myscript.js"
+    ]
+  }
+]
+</code>