Skocz do zawartości
Zaloguj się, aby obserwować  
Invisionize.eu

[Dokumentacja IPS4] Plugins (*)

Polecane posty

Introduction

Plugins provide a way for developers to modify or extend the behaviour of applications within the IPS Community Suite.

This guide will cover in detail the different features available within Plugins. Many of the features describes are accessed from the Plugin Developer Center - to access this, first place IPS Community Suite in developer mode. Once developer mode is enabled, a "Create Plugin" button will appear in the Admin CP under System --> Site Features --> Plugin. Use this tool to create your plugin, after which you'll be taken into the Plugin Developer Center.

Useful links for further reading:

Plugin Features


Code Hooks

Code Hooks allow you to extend any class within the IPS Community Suite or an application installed. You can create Code Hooks in the Plugin Developer Center.

You'll notice that throughout the code, classes are defined beginning with an underscore, but called without. For example, in /system/Member/Member.php, the declaration for is:

namespace IPS;
class _Member extends \IPS\Patterns\ActiveRecord

Yet throughout the code, \IPS\Member is called rather than \IPS\_Member. This is a technicality in how code hooks are facilitated. When creating your code hook, specify the class you want to extend without the underscore. When you're actually editing the code, it will say "extends _HOOK_CLASS_" - this is because the actual class it will extend will vary if more than one hook is overloading the same class.

You can edit code hooks either in the Plugin Developer Center or by manually editing the file which will have been created in /plugins/<your plugin>/hooks. Using the Plugin Developer Center has the benefit that all the properties and methods of the class you're extending (and classes that class extends) are shown in the sidebar, and clicking on any one will insert the declaration with the doc-comment into the editor.

1.png

Important things to remember when creating code hooks:

  • The first line in the class that is created is //<?php - this is so if you want to edit the file in your own editor that syntax highlighting works properly, however the <?php tag should not be used uncommented.
  • Your hook will specify that it extends _HOOK_CLASS_ - though this is syntaxually wrong, this should not be changed. The system will automatically change it to the correct class which may vary if there is more than one hook on a single class.
  • If your code causes a PHP error or throws a RuntimeException, your hook will be ignored and the system will revert to the default class. If you need to deliberately throw an exception, throw an object of an appropriate exception class.
  • When overriding a method, you MUST call the parent method so that ultimately you are inserting your code at the beginning or end of the method. This is necessary for allowing hooks on the same method to work.
  • When overriding a method, you MUST NOT copy code from the original method into your hook. This is necessary to ensure that your hook does not interfere with any bug fixes or changes made to the original class in future versions. Also, it is against the terms of the IPS Community Suite license to distribute any code within it.

Theme Hooks

Theme hooks allow you to modify the HTML templates. The HTML templates within the IPS Community Suite are structured into groupslocations and applications. Each application will have at least 3 locations:

  • front (templates used for the front-end)
  • admin (templates used for the Admin CP)
  • global (templates which are used for both)

Though some applications may have more for specific purposes (for example, the core application has another location for installer/upgrader called setup). Each location can contain any number of groups - groups are generic collections of templates, for example, the core application has one group (in the front location) called messaging which contains all the templates for composing and viewing personal conversations.

One Theme Hook acts on one template group.

You can create Theme Hooks in the Plugin Developer Center. Once created there are two ways to use Theme Hooks - each of which work differently and so will be appropriate for different circumstances:


CSS-Selector Mode

Editing your Theme Hook in the Plugin Developer Center will display a panel showing all of the templates in that group:
2.png

Selecting any template will bring up a tabbed interface showing the modifications your Theme Hook is making to that template, and allow to create more:
3.png

To make a modification to the selected template, you will provide a CSS selector - you can use any of the selectors supported by jQuery (it's worth mentioning that jQuery isn't involved in making your Theme Hook work, it is simply that the supported selectors are the same). The easiest way to choose a selector is with the interactive "Select Element" feature, which will launch a model displaying the template allowing you to simply click on the element you want to use:
4.png
It is important to note that when using the "Select Element" feature, it will use the most specific CSS selector it can for the element selected, however, that selector may also match other elements so you may need to adjust it.

When providing the content, in addition to the variables that are available to the template (which are shown next to the editor) you can also use any variables available at that point in the template (for example, if you're inserting code within a foreach loop, you can use the variables created by it). You can also use template logic and template tags.


PHP Mode

Under the hood, each template group is compiled into a PHP class, with a method for each template. You can extend this class by manually editing the file which will have been created in /plugins/<your plugin>/hooks.

It is important to note that when using this mode, you are overloading the compiled template group so the return value will be the HTML that will be displayed, without any template logic or template tags.]

All of the same considerations as for Code Hooks (see "Important things to remember when creating code hooks") also apply here.


Settings

Allocating space in IPS\Settings

IPS\Settings is a repository for scalar key/value data pairs - it is shared amongst all applications and plugins and is accessible from anywhere as a Singleton, there are also shortcuts to access it's contents within templates. It's primary intention is for storing settings the administrator provides in the Admin CP.

In order to use this, you must enter the keys you want to be allocated to your plugin and the default values in the Plugin Developer Center. The keys are not namespaced, so it is recommended that you choose keys that are unlikely to be used by other applications or plugins.

Creating a settings page

Your plugin is allowed to have one settings page which will be displayed with the administrator clicks the "edit" button next to your plugin. In most cases, this will be just a regular form using the form helper, however, though the form helper is very flexible (it can handle tabs, sidebars and a wide variety of input types), you are not restricted to this and can display your settings however you like.

In the /plugins/<your plugin> directory, you'll find a file called "settings.rename.php" - rename this to "settings.php" and this will be the code that runs when the user accesses your settings page. The example file is written with the form helper in mind, and to use that, all you need to do is add additional input fields. If you want to use a custom interface though, you just need to return either a string (with the content to display) or TRUE to dismiss the settings page. Your code will be eval'd and so you should not include an opening <?php tag - one is included in the example file so that syntax highlighting will work in most code editors, however it is commented out.


Tasks

Tasks are scripts which run at specific intervals. They are useful for performing any maintenance that must be ran on a regular basis. It is important to note however, that they cannot be relied on - though IPS Community Suite provides a way for administrators to run tasks using a cron, this may not be enabled, in which case tasks can only be triggered when users are active on the site - if the site is inactive at the time your task is scheduled to run, it will run at the soonest opportunity after.

You can create tasks in the Plugin Developer Center. When you create a task, a file will automatically be created in the /plugins/<your plugin>/tasks directory for your task. The doc-comments in this file explain how to implement the task.


Database changes (Versions)

Installs

To run code such as database changes when your plugin is installed, open the /plugins/<your plugin>/dev/setup/install.php file and follow the instructions given by the doc-comments.

Upgrades

Plugins support version management. Whenever you release a new version of your plugin you should add a new version in the Plugin Developer Center. When you add a version, you must specify an ID number to represent it (e.g. "10000", "10001", etc.) as well as a human-readable string (e.g. "1.0.0", "1.0.1", etc.). There is no particular standard to how the ID number should be formatted other than it must increase the newer the version. The human-readable string should be in the format "x.y.z".

For each version, a file will be added to the /plugins/<your plugin>/dev/setup folder where you can specify code that will be ran when upgrading to that version (see the doc-comments within them for more details).

It is important to note that at install, only install will be ran, so when you make a change you will usually need to add it both to your installer, and the appropriate upgrade file for that version.

HTML, CSS, JavaScript and Images

You can place HTML, CSS, JavaScript and image files in the appropriate folders in /plugins/<your plugin directory>/dev.


HTML

HTML files will become templates within the core application > global location > plugins group. In other words, you will get the content of the HTML files you create using this code in controllers:

\IPS\Theme::i()->getTemplate( 'plugins', 'core', 'global' )->FILENAME( ... );

Or the following code in other templates:

{template="FILENAME" group="plugins" location="global" app="core"}

You should create your files using the extension ".phtml". The first line of the file should be the following tag:

<ips:template parameters="$example1, $example2" />

Replacing $example1, $example2 with the names of whatever variables you intend to pass in. It is fine to have no parameters.

After that opening line, the remainder of the file should just be what you want the template contents to be. You can use template logic and template tags. Note that if any of the code in your template causes an exception to be thrown (which could happen if you're using particularly complicated template logic/tags without proper try/catch statements) the contents of the template will be ignored and will return an empty string.


CSS and JavaScript

Any CSS and JavaScript files you create will be compiled with the rest of the CSS and JavaScript automatically, so you do not need to do anything other than create the files.


Images

Images will be placed in the core application > global location, in a folder called plugins. In other words, you will render the images you place in the "img" directory by using this code in templates:

<img src='{resource="plugins/example.jpg" app="core" location="global"}' />

You must put all images directly in the "img" directory, do not create subdirectories.



Language Strings

IPS Community Suite supports multiple languages and translation tools such as the Visual Language Editor. Any text your plugin uses should be abstracted to language strings so that your plugin also supports these features.

Language strings are defined as key/value pairs. To add a language string, just open the /plugins/<your plugin>/dev/lang.php file and add an element to the array. Then to use the language string, use this in controllers:

\IPS\Member::loggedIn()->language()->get( 'KEY' );

Or this in templates:

{lang="KEY"}

 

Widgets

Widgets are blocks which can be added to the sidebar, header or footer on any page in the suite and the Pages application. You can create and widgets in the Plugin Developer Center. After creating the widget, a PHP file will be created in the widgets folder of your application or plugin with a skeleton to get you started. Simply follow the instructions in the source code to make your widget work.

 

Distribution

You can download your plugin from the Plugin Developer Center which will download a single XML file. This will automatically handle building all of the above features.

Wyświetl pełny artykuł

Udostępnij ten post


Link to postu
Udostępnij na innych stronach

Bądź aktywny! Zaloguj się lub utwórz konto

Tylko zarejestrowani użytkownicy mogą komentować zawartość tej strony

Zaloguj się, aby obserwować  

  • Kto przegląda   0 użytkowników

    Brak zalogowanych użytkowników przeglądających tę stronę.

×

Ważne informacje

Kontynuując przeglądanie strony, wyrażasz zgodę na używanie przez nas plików cookies.