构建OctoberCMS插件：Google Analytics（分析）

OctoberCMS is one of the rising stars in content management systems, and as in every CMS we need plugins to extend the functionality. In this article, we’re going to go through the basics of creating a plugin for October CMS.

OctoberCMS是内容管理系统中的后起之秀之一 ，就像每个CMS中一样，我们需要插件来扩展功能。 在本文中，我们将介绍为October CMS创建插件的基础。

我们正在建设 (What we’re building)

Almost all websites need Google Analytics. We’re going to make a plugin that inserts the Google Analytics tracking code into the page using a component tag.

几乎所有网站都需要Google Analytics(分析)。 我们将要制作一个插件，该插件使用component标签将Google Analytics(分析)跟踪代码插入页面。

After inserting your tracking id in the settings form, you’ll need to insert the component tag on the pages that you want to track, or inside a partial.

在设置表单中插入跟踪ID后，您需要在要跟踪的页面或部分页面中插入组件标签。

{% component 'gaCode' %}

You can see the final result on github and try it out.

您可以在github上查看最终结果并进行尝试。

管理插件 (Managing Plugins)

October has a plugins folder inside the root directory, where you can find, install, remove and develop plugins.

October在根目录内有一个plugins文件夹，您可以在其中找到，安装，删除和开发插件。

To manage your plugins, you can click the System > updates link. We have two different ways to manage our plugins.

要管理插件，可以单击System > updates链接。 我们有两种不同的方式来管理我们的插件。

创建一个新项目 (Creating a New Project)

Under the System > Updates page, you have an attach project link.

在“ System > Updates页面下，您具有一个attach project链接。

To attach a project you need to sign up on the October CMS website, go under the projects page, and you can create a new one.

要附加一个项目，您需要在October CMS网站上注册，请转到“项目”页面下方，然后可以创建一个新项目。

After creating the project you’ll have a key that you can use to attach a project. You can add a plugin from the marketplace to your project and update your website under the updates page on the back end.

创建项目后，您将拥有一个可用于附加项目的密钥。 您可以从市场将插件添加到项目中，并在后端的“更新”页面下更新您的网站。

使用命令行 (Using The Command Line)

Another way to install new plugins is through the command line, but you still need to find the plugin name on the website (which is quite annoying). At the time of this writing, to install a new plugin you need to specify Author.PluginName to find it.

安装新插件的另一种方法是通过命令行 ，但是您仍然需要在网站上找到插件名称(这很烦人)。 在撰写本文时，要安装新插件，您需要指定Author.PluginName才能找到它。

创建一个新插件 (Creating A New Plugin)

脚手架 (Scaffolding)

October CMS made creating a new plugin as easy as possible. You either create a new folder inside the pluginsdirectory or use the command line helper.

October CMS使创建新插件尽可能容易。 您可以在plugins目录内创建一个新文件夹，也可以使用命令行帮助器。

The folder name is your unique namespace that you’ll be using publicly, and it should not conflict with others.

文件夹名称是您将要公开使用的唯一名称空间，并且不应与其他名称冲突。

To get your unique namespace, you need to register as an author on the October CMS website and register your namespace.

要获得唯一的名称空间，您需要在October CMS网站上注册为作者并注册您的名称空间。

Under the plugins folder, I will create a folder named RAFIE which is my namespace, where I can put all my plugins.

在plugins文件夹下，我将创建一个名为RAFIE的文件夹，这是我的命名空间，我可以在其中放置所有插件。

For this article, we will name our plugin GoogleAnalyticsCode. Under this folder, we only need to create a file named Plugin.php to define our plugin.

对于本文，我们将其插件命名为GoogleAnalyticsCode 。 在此文件夹下，我们只需要创建一个名为Plugin.php的文件来定义我们的插件。

The other way to get started is to use a scaffolding command provided by October.

另一种入门方法是使用October提供的脚手架命令。

php artisan create:plugin RAFIE.GoogleAnalyticsCode

The command also adds a folder named uploads which contains a version.yaml file that keeps your plugin’s versioning history.

该命令还添加了一个名为uploads的文件夹，其中包含一个version.yaml文件，该文件保留了插件的版本控制历史记录。

The pluginDetails method overridden from the System\Classes\PluginBase class must return an array defining our plugin.

从System\Classes\PluginBase类重写的pluginDetails方法必须返回定义我们的插件的数组。

public function pluginDetails(){ return [ 'name' => 'Google Analytics Code', 'description' => 'Insert Google Analytics tracking code inside you pages', 'author' => 'RAFIE Younes', 'icon' => 'icon-bar-chart-o' ]; }

You can check the doc for the complete list of methods, but we will explore each one in depth later.

您可以在文档中查看完整的方法列表，但是稍后我们将深入探讨每个方法。

Note that if the plugin is not appearing on the list of registered plugins, press the check for updates button to refresh the list.

请注意，如果该插件未出现在已注册插件列表中，请按“ check for updates按钮以刷新列表。

使用组件 (Using Components)

To be able to interact with the page, October uses components, which allow the user to insert the plugin to interact with their pages or partials.

为了能够与页面进行交互，October使用了组件，该组件允许用户插入插件以与其页面或部分进行交互。

{% component 'gaCode' %}

To create a component, you need to create a folder named components, and put any classes that you’ll be using in there.

要创建组件，您需要创建一个名为components的文件夹，并将要使用的所有类放在其中。

Instead of creating those files and folders, we can use console util commands provided by October.

除了创建这些文件和文件夹，我们还可以使用October提供的控制台实用程序命令。

php artisan create:component RAFIE.GoogleAnalyticsCode GoogleAnalytics

The componentDetails method overridden from the Cms\Classes\ComponentBase is where we define our component. The name and description are going to be shown on the admin dashboard.

从Cms\Classes\ComponentBase重写的componentDetails方法是定义组件的地方。 名称和说明将显示在管理控制台上。

To register a component, we need to override the registerComponents method inside the Plugin class.

要注册组件，我们需要重写Plugin类中的registerComponents方法。

public function registerComponents(){ return [ 'RAFIE\GoogleAnalyticsCode\Components\GoogleAnalytics' => 'gaCode' ]; }

We basically return an array of class names and component names. Every plugin can register multiple components.

我们基本上返回一个类名和组件名的数组。 每个插件都可以注册多个组件。

After the component is executed, it will render the default.htm partial, which by default will output:

执行完组件后，它将呈现default.htm部分，默认情况下将输出：

<p>This is the default markup for component GoogleAnalytics</p> <small>You can delete this file if you want</small>

We will alter this content with the Google Analytics tracking code from Google.

我们将使用Google的Google Analytics(分析)跟踪代码来更改此内容。

<script> (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) })(window,document,'script','//www.Google-analytics.com/analytics.js','ga'); ga('create', 'YOUR TRACKING CODE HERE', 'auto'); ga('send', 'pageview'); </script>

Of course, the tracking code script needs to be loaded at the end of the page, but that will depend on your theme.

当然，跟踪代码脚本需要在页面末尾加载，但这取决于您的主题。

The default page must receive the tracking code from the user, that’s where we can use component properties.

默认页面必须从用户那里接收跟踪代码，这是我们可以使用组件属性的地方。

组件属性 (Component Properties)

{% component 'gaCode' code='UA-12345678-1' %}

To define properties you can use the defineProperties method, and must return an array of available properties.

要定义属性，可以使用defineProperties方法，并且必须返回可用属性的数组。

public function defineProperties(){ return [ 'code' => [ 'title' => 'Google Analytics tracking code', 'description' => 'Your Google Analytics tracking code, can be found in your Google Analytics dashboard', 'default' => '', 'type' => 'string', 'validationPattern' => '^UA-\d{4,9}-\d{1,4}$', 'validationMessage' => 'Not a tracking code', 'placeholder' => 'UA-XXXXXXX' ] ]; }

The array keys are self descriptive, you can check the docs for more details.

数组键是自描述的，您可以查看文档以获取更多详细信息。

You can either use the form or manually enter the property. Now we need to catch the value and pass it to the partials.

您可以使用表单或手动输入属性。 现在我们需要捕获值并将其传递给局部变量。

Inside our class component we have an onRender method where we can pass the values to our page.

在我们的类组件内部，我们有一个onRender方法，可以将值传递给页面。

public function onRender(){ $this->page['code'] = $this->property('code'); }

The ComponentBase class has a page attribute that represents the rendered page.

ComponentBase类具有一个page属性，该属性表示呈现的页面。

<script> (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) })(window,document,'script','//www.Google-analytics.com/analytics.js','ga'); ga('create', '{{ code }}', 'auto'); ga('send', 'pageview'); </script>

In most cases, you don’t want to write your tracking code on every page using properties. The best way is to have a settings form where the user can enter his code once.

在大多数情况下，您不想使用属性在每个页面上编写跟踪代码。 最好的方法是拥有一个设置表单，用户可以在其中输入一次代码。

使用设定 (Using Settings)

Plugin settings go under the models directory. The plugin structure should look something like this.

插件设置位于models目录下。 插件结构应如下所示。

The Settings.php file is where we can define our settings. The class should extend the Laravel Model class.

我们可以在Settings.php文件中定义设置。 该类应扩展Laravel Model类。

// googleanalyticscode/models/GoogleAnalyticsSettings.php class GoogleAnalyticsSettings extends Model{ public $implement = ['System.Behaviors.SettingsModel']; public $settingsCode = 'rafie_google_analytics_code'; public $settingsFields = 'fields.yaml'; }

Every settings form should implement the SettingsModel from the October CMS core.

每个设置表单都应从October CMS核心实现SettingsModel 。

The settingsCode attribute is our unique key that we should be using when saving to the database.

settingsCode属性是保存到数据库时应使用的唯一键。

settingsFields is the file name where we define our form settings fields. The CMS will look in a folder named the same as the settings class file.

settingsFields是在其中定义表单设置字段的文件名。 CMS将在与设置类文件相同的文件夹中查找。

// fields.yaml fields: code: label: Your Google Analytics ID placeholder: UA-XXXXXXXX-X

We define only one input where we can put our tracking code. You can also define a password field, a datepicker or a list of options; be sure to check the list of available options.

我们只定义了一个输入，可以放置我们的跟踪代码。 您还可以定义密码字段，日期选择器或选项列表。 确保检查可用选项列表 。

The only remaining part is to register our settings form inside our plugin file.

剩下的唯一部分是在插件文件中注册我们的设置表单。

public function registerSettings(){ return [ 'settings' => [ 'label' => 'Google Analytics Code', 'description' => 'Manage Google Analytics Settings.', 'icon' => 'icon-bar-chart-o', 'class' => 'RAFIE\GoogleAnalyticsCode\Models\GoogleAnalyticsSettings', 'order' => 1 ] ]; }

The label and description are shown in the left menu on the dashboard. We also define an icon, and a position in the menu.

标签和说明显示在仪表板上的左侧菜单中。 我们还定义了一个图标，以及在菜单中的位置。

After updating the settings and visiting the database, you should see your settings saved with your unique ID.

更新设置并访问数据库后，您应该会看到使用唯一ID保存的设置。

Now we need to retrieve the user settings and pass them to our component partial. Initially, we did it using a property. We need to make some changes inside our component class now.

现在，我们需要检索用户设置，并将它们传递给组件部分。 最初，我们使用属性来完成此操作。 现在，我们需要在组件类中进行一些更改。

//Plugin.php public function onRender(){ $settings = GoogleAnalyticsSettings::instance(); $this->page['code'] = $settings->code; }

We create an instance of the model, then we access our code field as a property. This will give the same result as the previous one.

我们创建模型的实例，然后将代码字段作为属性访问。 这将产生与上一个相同的结果。

结论 (Conclusion)

October is a really promising CMS with a different way of handling plugins and themes. You can learn a lot more by diving into the source code and being one of the early adopters. We will have more in depth articles about plugins and themes, but for now let us know what you think about this introduction in the comments below.

October是一个非常有前途的CMS，它具有处理插件和主题的不同方式。 深入研究源代码并成为早期采用者之一，您可以学到更多。 我们将提供有关插件和主题的更深入的文章，但现在让我们在下面的评论中告诉您您对此介绍的看法。

翻译自: https://www.sitepoint.com/building-octobercms-plugins-google-analytics/

相关资源：jdk-8u281-windows-x64.exe