16 | require_once __DIR__ . '/lib/Mautic/MauticApi.php'; 17 |18 | 19 | -------------------------------------------------------------------------------- /source/stylesheets/icon-font.scss: -------------------------------------------------------------------------------- 1 | %icon { 2 | font-family: 'FontAwesome'; 3 | speak: none; 4 | font-style: normal; 5 | font-weight: normal; 6 | font-variant: normal; 7 | text-transform: none; 8 | line-height: 1; 9 | } 10 | 11 | %icon-exclamation-sign { 12 | @extend %icon; 13 | content: "\f12a"; 14 | } 15 | %icon-question-sign { 16 | @extend %icon; 17 | content: "\f128"; 18 | } 19 | %icon-info-sign { 20 | @extend %icon; 21 | content: "\f129"; 22 | } 23 | %icon-remove-sign { 24 | @extend %icon; 25 | content: "\f00d"; 26 | } 27 | %icon-plus-sign { 28 | @extend %icon; 29 | content: "\f067"; 30 | } 31 | %icon-minus-sign { 32 | @extend %icon; 33 | content: "\f068"; 34 | } 35 | %icon-ok-sign { 36 | @extend %icon; 37 | content: "\f00c"; 38 | } 39 | %icon-search { 40 | @extend %icon; 41 | content: "\f002"; 42 | } 43 | %icon-open { 44 | @extend %icon; 45 | content: "\f0da"; 46 | } 47 | %icon-close { 48 | @extend %icon; 49 | content: "\f0d7"; 50 | } 51 | -------------------------------------------------------------------------------- /source/includes/_plugin_migrations_1.2.md: -------------------------------------------------------------------------------- 1 | ### 1.2.0 2 | 3 | 1.2.0 deprecated the Mautic Addon with it's successor, the Plugin. Mautic addons will continue to work but should be migrated to a plugin before Mautic 2.0 when support will be dropped. 4 | 5 | The migration path is as follows: 6 | 7 | 1. Move the plugin from addons/ to plugins/ 8 | 2. Replace the namespace `MauticAddon` with `MauticPlugin` 9 | 3. Replace the MauticFactory getModel() notation of `addon.` to `plugin.` 10 | 4. Replace the permission notation of `addon:` to `plugin:` 11 | 5. Change the plugin's bundle class to extend `PluginBundleBase` instead of `AddonBundleBase` 12 | 6. In the plugin's bundle class, use the function's `onPluginInstall()` and `onPluginUpdate()` instead of the deprecated `onInstall()` and `onUpdate()` 13 | 7. Migrate Entity use of annotations for ORM to the static PHP function `loadMetadata()` 14 | 8. Migrate Entity use of annotations for the serializer (used with the REST API) to the static PHP function `loadApiMetadata()` -------------------------------------------------------------------------------- /source/includes/_plugin_services_model_factory.md: -------------------------------------------------------------------------------- 1 | ### Model Factory 2 | 3 | ```php 4 | hasModel($channel)) { 10 | $model = $modelFactory->getModel($channel); 11 | 12 | if ($entity = $model->getEntity($channelId)) { 13 | echo $entity->getName(); 14 | } 15 | } 16 | ``` 17 | 18 | `Mautic/CoreBundle/Factory/ModelFactory` can be used in services that a model dependency is unknown at the time the service is created. This is great for scenarios where the channel and channel ID are stored in a database and the executing code needs to obtain information on the channel entity (name, etc). 19 | 20 | It has two methods: `hasModel($modelNameKey)` and `getModel($modelNameKey)`. `hasModel` simple checks to see if a model exists. It uses the same format as using the controller helper method `getModel()`. For example, to obtain the `Mautic\EmailBundle\Model\EmailModel` class, you could use something like the code example. 21 | -------------------------------------------------------------------------------- /source/includes/_plugin_services_event_dispatcher.md: -------------------------------------------------------------------------------- 1 | ### Event Dispatcher 2 | ```php 3 | get('event_dispatcher'); 6 | if ($dispatcher->hasListeners(HelloWorldEvents::ARMAGEDDON)) { 7 | $event = $dispatcher->dispatch(HelloWorldEvents::ARMAGEDDON, new ArmageddonEvent($world)); 8 | 9 | if ($event->shouldPanic()) { 10 | throw new \Exception("Run for the hills!"); 11 | } 12 | } 13 | ``` 14 | 15 | * Service name: `event_dispatcher` 16 | * Class: `Symfony\Component\EventDispatcher\EventDispatcher` 17 | * Implements `Symfony\Component\EventDispatcher\EventDispatcherInterface` (When type hinting, use this class since different environments may use different classes for the dispatcher) 18 | * Docs: [http://symfony.com/doc/2.8/components/event_dispatcher/introduction.html#dispatch-the-event](http://symfony.com/doc/2.8/components/event_dispatcher/introduction.html#dispatch-the-event) 19 | 20 | Dispatch [custom events](#custom-events) using the `event_dispatcher` service. 21 | -------------------------------------------------------------------------------- /source/includes/_plugin_services_session.md: -------------------------------------------------------------------------------- 1 | ### Session 2 | 3 | ```php 4 | get('session'); 7 | $requestSession = $request->getSession(); // Shortcut to session 8 | 9 | // Get all session parameters 10 | $all = $session->all(); 11 | 12 | // Get specific parameter setting mars as default 13 | $world = $session->get('helloworld.world', 'mars'); 14 | 15 | // Check if a parameter exists 16 | if ($session->has('helloworld.world')) { 17 | // do something 18 | } 19 | 20 | // Set a session parameter 21 | $session->set('helloworld.world', 'mars'); 22 | 23 | // Remove a session parameter 24 | $session->remove('helloworld.world'); 25 | 26 | // Clear the whole session 27 | $session->clear(); 28 | ``` 29 | 30 | * Service name: `session` 31 | * Class: `Symfony\Component\HttpFoundation\Session` 32 | * Docs: [http://symfony.com/doc/2.8/components/http_foundation/sessions.html](http://symfony.com/doc/2.8/components/http_foundation/sessions.html) 33 | 34 | To access the session service in a view, use `$app->getSession()`. -------------------------------------------------------------------------------- /source/includes/_api_authorization.md: -------------------------------------------------------------------------------- 1 | 2 | ## Authorization 3 | 4 | Mautic uses OAuth or Basic Authentication (as of Mautic 2.3.0) for API authorization. It supports both [OAuth 1a](http://tools.ietf.org/html/rfc5849) and [OAuth 2](https://tools.ietf.org/html/rfc6749); however, as of 1.1.2, the administrator of the Mautic instance must choose one or the other. Of course OAuth 2 is only recommended for servers secured behind SSL. Basic authentication must be enabled in Configuration -> API Settings. 5 | 6 | The Mautic administrator should enable the API in the Configuration -> API Settings. This will add the "API Credentials" to the admin menu. A client/consumer ID and secret should then be generated which will be used in the following processes. 7 | 8 | All authorization requests should be made to the specific Mautic instances URL, i.e. `https://your-mautic.com`. 9 | 10 | -------------------------------------------------------------------------------- /source/includes/marketplace.md: -------------------------------------------------------------------------------- 1 | # Marketplace 2 | 3 | Mautic 4 comes with a Marketplace directly in the Mautic administration user interface and command line interface as well. 4 | 5 | ## Marketplace under the hood 6 | 7 | The Marketplace use [Packagist](https://packagist.org) and [Composer](https://getcomposer.org) v2 under the hood. Packagist API is used to list the Mautic plugins and find the plugin details. Composer v2 is used to install and update the plugins. Composer will take care of the dependencies of your plugin and also compatibility with different Mautic, PHP and other dependecies versions. 8 | 9 | ## How to list a plugin in the Mautic Marketplace 10 | 11 | Please check the resources on the [WIP new Developer Documentation](https://mautic-developer.readthedocs.io/en/latest/marketplace/listing.html) 12 | 13 | ## How to get included in the allow-list 14 | 15 | Please check the resources on the [WIP new Developer Documentation](https://mautic-developer.readthedocs.io/en/latest/marketplace/listing.html) 16 | 17 | ## Best Practices 18 | 19 | Please check the best practices on the [WIP new Developer Documentation](https://mautic-developer.readthedocs.io/en/latest/marketplace/best_practices.html) 20 | -------------------------------------------------------------------------------- /source/includes/_plugin_services_router.md: -------------------------------------------------------------------------------- 1 | ### Router 2 | 3 | ```php 4 | get('router'); 7 | 8 | // Relative URL 9 | $url = $router->generateUrl('plugin_helloworld_admin'); 10 | 11 | // URL with placeholders 12 | $url = $router->generateUrl('plugin_helloworld_world', array('%world%', 'mars')); 13 | 14 | // Absolute URL 15 | $absoluteUrl = $router->generateUrl('plugin_helloworld_admin', array(), true); 16 | ``` 17 | 18 | ```php 19 | generate('plugin_helloworld_admin'); // result is /hello/admin 22 | 23 | // Generate a path in a view template 24 | $path = $view['router']->path('plugin_helloworld_admin'); // result is /hello/admin 25 | $url = $view['router']->url('plugin_helloworld_admin'); // result is http://yoursite.com/hello/admin 26 | 27 | ``` 28 | 29 | * Service name: `router` 30 | * Class: `Symfony\Bundle\FrameworkBundle\Routing\Router` 31 | * Docs: [https://symfony.com/doc/2.8/routing.html#generating-urls](https://symfony.com/doc/2.8/routing.html#generating-urls) 32 | 33 | For views, use the `$view['router']` helper. The difference with the [template helper](#router-helper) is that `url()` or `path()` is used instead of `generateUrl()` of the `router` service. 34 | -------------------------------------------------------------------------------- /config.rb: -------------------------------------------------------------------------------- 1 | set :css_dir, 'stylesheets' 2 | 3 | set :js_dir, 'javascripts' 4 | 5 | set :images_dir, 'images' 6 | 7 | set :fonts_dir, 'fonts' 8 | 9 | set :markdown_engine, :redcarpet 10 | 11 | set :markdown, :fenced_code_blocks => true, :smartypants => true, :disable_indented_code_blocks => true, :prettify => true, :tables => true, :with_toc_data => true, :no_intra_emphasis => true 12 | 13 | # Activate the syntax highlighter 14 | activate :syntax 15 | 16 | # This is needed for Github pages, since they're hosted on a subdomain 17 | activate :relative_assets 18 | set :relative_links, true 19 | 20 | # Build-specific configuration 21 | configure :build do 22 | # For example, change the Compass output style for deployment 23 | activate :minify_css 24 | 25 | # Minify Javascript on build 26 | activate :minify_javascript 27 | 28 | # Enable cache buster 29 | # activate :asset_hash 30 | 31 | # Use relative URLs 32 | # activate :relative_assets 33 | 34 | # Or use a different image path 35 | # set :http_prefix, "/Content/images/" 36 | end 37 | 38 | activate :deploy do |deploy| 39 | deploy.method = :sftp 40 | deploy.port = 22 41 | deploy.path = ENV["SSH_DEPLOYMENT_PATH"] 42 | deploy.host = ENV["SSH_HOST"] 43 | deploy.user = ENV["SSH_USER"] 44 | deploy.password = ENV["SSH_PASSWORD"] 45 | end 46 | -------------------------------------------------------------------------------- /source/includes/_plugin_integrations_builder.md: -------------------------------------------------------------------------------- 1 | ### Integration Builders 2 | Builders can register itself as a "builder" for email and/or landing pages. 3 | 4 | #### Registering the Integration as a Builder 5 | To tell the IntegrationsBundle that this integration has configuration options, tag the integration or support class with `mautic.config_integration` in the plugin's `app/config.php`. 6 | 7 | ```php 8 | [ 12 | // ... 13 | 'integrations' => [ 14 | // ... 15 | 'helloworld.integration.builder' => [ 16 | 'class' => \MauticPlugin\HelloWorldBundle\Integration\Support\BuilderSupport::class, 17 | 'tags' => [ 18 | 'mautic.builder_integration', 19 | ], 20 | ], 21 | // ... 22 | ], 23 | // ... 24 | ], 25 | // ... 26 | ]; 27 | ``` 28 | 29 | The `BuilderSupport` class must implement `\Mautic\IntegrationsBundle\Integration\Interfaces\BuilderInterface`. 30 | 31 | The only method currently defined for the interface is `isSupported` which should return a boolean if it supports the given feature. Currently, Mautic supports `email` and `page` (landing pages). This will determine what themes should be displayed as an option for the given builder/feature. 32 | -------------------------------------------------------------------------------- /source/includes/_plugin_migrations_2.0.md: -------------------------------------------------------------------------------- 1 | ### 2.0.0 2 | 3 | The big ticket item with 2.0.0 is the deprecation of MauticFactory which will be phased out during the 2.x release cycles and to be removed in 3.0. Where possible, please use direct dependency injection of services rather than relying on MauticFactory. 4 | 5 | 1. MauticFactory deprecated - use dependency injection of required services. Many MauticFactory helper functions have been replaced with [services](#services). 6 | 2. Models need to be registered as services using a specific nomenclature. See [Models](#models) for more information. 7 | 3. The static callback function for campaign actions and decisions has been deprecated. Please see [Extending Campaigns](#extending-campaigns) for more information on the new event based method. (Form submit actions, point triggers, and the like will follow suit with a similar migration throughout the lifecycle of 2.0 but for now still uses the static callback method). 8 | 4. Minimum PHP version has been increased to 5.6.19 and thus newer PHP code goodies are available for developers (traits, etc) 9 | 5. Themes have been completely revamped although the old format is still supported for now. Please see [Themes](#themes) for the new format. 10 | 6. Some routes for /leads/* were removed in favor of /contacts/*. I.e. /api/leads is now /api/contacts, /s/leads is now /s/contacts, and so forth. The route names were also updated. For example, `mautic_lead_action` is now `mautic_contact_action` and so forth. -------------------------------------------------------------------------------- /source/includes/_plugin_services_security.md: -------------------------------------------------------------------------------- 1 | ### Security 2 | 3 | ```php 4 | get('mautic.security'); 7 | 8 | // Check if user is granted a single permission 9 | if ($security->isGranted('plugin:helloWorld:worlds:view')) { 10 | // do something 11 | } 12 | 13 | // Check if user is granted multiple permissions (must be granted to all to be true) 14 | if ($security->isGranted( 15 | array( 16 | 'plugin:helloWorld:worlds:view', 17 | 'plugin:helloWorld:worlds:create', 18 | ) 19 | ) 20 | ) { 21 | //do something 22 | } 23 | 24 | // Check if user is granted to at least one permission 25 | if ($security->isGranted( 26 | array( 27 | 'plugin:helloWorld:worlds:view', 28 | 'plugin:helloWorld:worlds:edit', 29 | ), 30 | 'MATCH_ONE' 31 | ) 32 | ) { 33 | //do something 34 | } 35 | 36 | // Get an array of user permissions 37 | $permissions = $security->isGranted( 38 | array( 39 | 'plugin:helloWorld:worlds:view', 40 | 'plugin:helloWorld:worlds:edit', 41 | ), 42 | 'RETURN_ARRAY' 43 | ); 44 | 45 | if ($permissions['plugin:helloWorld:worlds:view']) { 46 | // do something 47 | } 48 | 49 | // Check to see if a user is anonymous (not logged in) 50 | if ($security->isAnonymous()) { 51 | // do something 52 | } 53 | ``` 54 | 55 | * Service name: `mautic.security` 56 | * Class: `Mautic\CoreBundle\Security\Permissions\CorePermissions` 57 | 58 | Using the service to check permissions is explained more in [Using Permissions](#using-permissions). -------------------------------------------------------------------------------- /source/includes/_api_intro.md: -------------------------------------------------------------------------------- 1 | # REST API 2 | 3 | Mautic provides a REST API to manipulate leads and/or obtain information for various entities of Mautic. 4 | 5 | 8 | 9 | ## Error Handling 10 | 11 | If an OAuth error is encountered, it'll be a JSON encoded array similar to: 12 | 13 |
14 | {
15 | "error": "invalid_grant",
16 | "error_description": "The access token provided has expired."
17 | }
18 |
19 |
20 | If a system error encountered, it'll be a JSON encoded array similar to:
21 |
22 |
23 | {
24 | "error": {
25 | "message": "You do not have access to the requested area/action.",
26 | "code": 403
27 | }
28 | }
29 |
30 |
31 | ## Mautic version check
32 |
33 | In case your API service wants to support several Mautic versions with different features, you might need to check the version of Mautic you communicate with. Since Mautic 2.4.0 the version number is added to all API response headers. The header name is `Mautic-Version`. With Mautic PHP API library you can get the Mautic version like this:
34 |
35 | ```
36 | // Make any API request:
37 | $api = $this->getContext('contacts');
38 | $response = $api->getList('', 0, 1);
39 |
40 | // Get the version number from the response header:
41 | $version = $api->getMauticVersion();
42 | ```
43 | `$version` will be in a semantic versioning format: `[major].[minor].[patch]`. For example: `2.4.0`. If you'll try it on the latest GitHub version, the version will have `-dev` at the end. Like `2.5.1-dev`.
44 |
--------------------------------------------------------------------------------
/source/includes/_plugin_misc_commands.md:
--------------------------------------------------------------------------------
1 | ### Commands
2 |
3 | Support for new CLI commands can be added using [Symfony's console component](http://symfony.com/doc/2.8/console.html).
4 |
5 | #### Moderated Commands
6 |
7 | ```php
8 | checkRunStatus($input, $output)) {
44 | return 0;
45 | }
46 |
47 | // Execute some stuff
48 |
49 | // Complete this execution
50 | $this->completeRun();
51 |
52 | return 0;
53 | }
54 | }
55 | ```
56 |
57 | Mautic provide an method for moderating commands meaning it will only allow one instance to run at a time. To utilize this method, extend the `Mautic\CoreBundle\Command\ModeratedCommand` class.
58 |
59 |
--------------------------------------------------------------------------------
/source/includes/_plugin_misc_flashes.md:
--------------------------------------------------------------------------------
1 | ### Flash Messages
2 |
3 | ```php
4 | addFlash(
9 | 'mautic.translation.key',
10 | array('%placeholder%' => 'some text'),
11 | 'notice', // Notification type
12 | 'flashes', // Translation domain
13 | $addNotification // Add a notification entry
14 | );
15 | ```
16 |
17 | ```php
18 | translator->trans(,
23 | array(
24 | '%placeholder%' => 'some text'
25 | ),
26 | 'flashes'
27 | );
28 | $this->session->getFlashBag()->add('notice', $translatedString);
29 | ```
30 |
31 | To create an alert, aka flash message, you can use the flash bag in the session.
32 |
33 | If your controller extends one of [Mautic's common controllers](#controllers), you can simply use the helper function `addFlash()`.
34 |
35 | From a model, or any service, you can use the session to obtain the flash bag.
36 |
37 | `$flashBag = $this->get('session')->getFlashBag();`
38 |
39 | ### Notifications
40 |
41 | ```php
42 | addNotification($message, $type, $isRead, $header, $iconClass, new \DateTime());
46 | ```
47 |
48 | ```php
49 | addNotification($message, $type, $isRead, $header, $iconClass, $datetime );
54 |
55 | ```
56 | Mautic also has a notification center. By default, addFlash() will also add a notification to the center. But, a message can be manually added as well.
57 |
58 | Controllers can use the helper function while models and other services can obtain the NotificationModel.
59 |
--------------------------------------------------------------------------------
/source/includes/_plugin_services_request.md:
--------------------------------------------------------------------------------
1 | ### Request
2 | ```php
3 | get('request_stack')->getCurrentRequest();
6 |
7 | // $_GET
8 | $get = $request->query->all();
9 |
10 | // $_POST
11 | $post = $request->request->all();
12 |
13 | // $_COOKIE
14 | $cookies = $request->cookies->all();
15 |
16 | // $_SERVER
17 | $server = $request->server->all();
18 |
19 | // Headers
20 | $headers = $request->headers->all();
21 |
22 | // Attributes - custom parameters
23 | $headers = $request->attributes->all();
24 |
25 | // Check if a parameter exists
26 | if ($request->request->has('hello')) {
27 | // do something
28 | }
29 |
30 | // Retrieve value of a specific parameter setting mars as default
31 | $world = $request->query->get('world', 'mars');
32 |
33 | // Set custom request value
34 | $request->attributes->set('hello', 'world');
35 |
36 | // Get the value of a nested array
37 | $mars = $request->request->get('world[mars]', array(), true);
38 | ```
39 |
40 | * Service name: `request_stack`
41 | * Class: `Symfony\Component\HttpFoundation\RequestStack`
42 | * Docs: [http://symfony.com/doc/2.8/book/service_container.html#book-container-request-stack](http://symfony.com/doc/2.8/book/service_container.html#book-container-request-stack)
43 |
44 | There are multiple ways to obtain the request service.
45 |
46 | If the controller is extending one of [Mautic's controllers](#controllers), it is already available via `$this->request`. Alternatively, Symfony will [auto-inject the request object](http://symfony.com/doc/2.8/book/controller.html#the-request-object-as-a-controller-argument) into the controller action method if the variable is type-hinted as `Symfony\Component\HttpFoundation\Request`.
47 |
48 | For services, pass the `request_stack` service then use `$request = $requestStack->getCurrentRequest()`.
49 |
50 | From within a view, use `$app->getRequest()`.
--------------------------------------------------------------------------------
/source/includes/_plugin_structure.md:
--------------------------------------------------------------------------------
1 | ## Plugin Directory Structure
2 |
3 | ```php
4 |
23 | - - - Config/9 | 'categories' => array( 10 | 'plugin:helloWorld' => 'mautic.helloworld.world.categories' 11 | ), 12 |13 | 14 | The category keys need be prefixed with `plugin:` as it is used in determining permissions to manage categories. The `helloWorld` should match the permission class name. 15 | 16 | #### Configuring Categories for Menu 17 | 18 | It is now recommended to not show the category in the main Menu. 19 | 20 | To add a category menu item for the plugin, simply add the following to `menu` [config](#menu) for whichever menu the item should appear (`main` or `admin`): 21 | 22 |
23 | 'mautic.category.menu.index' => array( 24 | 'bundle' => 'plugin:helloWorld' 25 | ) 26 |27 | 28 | The `bundle` value needs be prefixed with `plugin:` as it is used in determining permissions to manage categories. The `helloWorld` should be the bundle name of the plugin. 29 | 30 | #### Configuring Categories for Routes 31 | 32 | There is no need to add custom routes for categories. However, when [generating a URL](#router) to the plugin's category list, use 33 | 34 |
35 | $categoryUrl = $router->generateUrl('mautic_category_index', array('bundle' => 'plugin:helloWorld'));
36 |
37 |
38 | #### Including Category in Forms
39 |
40 | To add a category select list to a [form](#forms), use `category` as the form type and pass `bundle` as an option:
41 |
42 |
43 | //add category
44 | $builder->add('category', 'category', array(
45 | 'bundle' => 'plugin:helloWorld'
46 | ));
47 |
48 |
49 | #### Restricting Category Management
50 |
51 | To restrict access to catgories, use the following in the plugin's [Permission class](#roles-and-permissions).
52 |
53 | In `__construct()` add `$this->addStandardPermissions('categories');` then in `buildForm()`, add `$this->addStandardFormFields('helloWorld', 'categories', $builder, $data);`.
54 |
55 | See a code example in [Roles and Permissions](#roles-and-permissions).
56 |
57 | The two standard helper methods will add the permissions of `view`, `edit`, `create`, `delete`, `publish`, and `full` for categories.
58 |
59 |
60 |
--------------------------------------------------------------------------------
/source/includes/_plugin_extending_points.md:
--------------------------------------------------------------------------------
1 | ### Extending Points
2 |
3 | Custom point actions and triggers can be added by listening to their respective on build events. Read more about [listeners and subscribers](#events).
4 |
5 | #### Point Actions
6 |
7 | To add a custom point action used to give a lead x points for doing a certain action, add a listener to the `\Mautic\PointBundle\PointEvents::POINT_ON_BUILD` event then configure the custom point action with `$event->addAction($identifier, $parameters)` method. `$identifier` must be something unique. The `$parameters` array can contain the following elements:
8 |
9 |
10 | Key|Required|Type|Description
11 | ---|--------|----|-----------
12 | **label**|REQUIRED|string|The language string for the option in the dropdown
13 | **formType**|OPTIONAL|string|The alias of a custom form type used to set config options.
14 | **formTypeOptions**|OPTIONAL|array|Array of options to include into the formType's $options argument
15 | **formTypeCleanMasks**|OPTIONAL|array|Array of input masks to clean a values from formType
16 | **formTypeTheme**|OPTIONAL|string|Theme to customize elements for formType
17 | **template**|OPTIONAL|string|View template used to render the formType
18 | **callback**|OPTIONAL|mixed|Static callback function used to validate the action. Return true to add the points to the lead.
19 |
20 | In order for the custom point action to work, add something like the following in the code logic when the lead executes the custom action:
21 |
22 |
23 | `$this->getModel('point')->triggerAction('page.hit', $event->getHit());`
24 |
25 |
26 | #### Point Triggers
27 |
28 |
29 | To add a custom point trigger used to execute a specific action once a lead hits X number of points, add a listener to the `\Mautic\PointBundle\PointEvents::TRIGGER_ON_BUILD` event then configure the custom point trigger with `$event->addEvent($identifier, $parameters)` method. `$identifier` must be something unique. The `$parameters` array can contain the following elements:
30 |
31 | Key|Required|Type|Description
32 | ---|--------|----|-----------
33 | **label**|REQUIRED|string|The language string for the option in the dropdown
34 | **formType**|OPTIONAL|string|The alias of a custom form type used to set config options.
35 | **formTypeOptions**|OPTIONAL|array|Array of options to include into the formType's $options argument
36 | **formTypeCleanMasks**|OPTIONAL|array|Array of input masks to clean a values from formType
37 | **formTypeTheme**|OPTIONAL|string|Theme to customize elements for formType
38 | **template**|OPTIONAL|string|View template used to render the formType
39 | **callback**|OPTIONAL|mixed|Static callback function used to execute the custom action.
--------------------------------------------------------------------------------
/source/javascripts/app/toc.js:
--------------------------------------------------------------------------------
1 | (function (global) {
2 |
3 | var closeToc = function () {
4 | $(".tocify-wrapper").removeClass('open');
5 | $("#nav-button").removeClass('open');
6 | };
7 |
8 | var makeToc = function () {
9 | global.toc = $("#toc").tocify({
10 | selectors: 'h1, h2, h3',
11 | extendPage: false,
12 | theme: 'none',
13 | smoothScroll: false,
14 | showEffectSpeed: 0,
15 | hideEffectSpeed: 180,
16 | ignoreSelector: '.toc-ignore',
17 | highlightOffset: 60,
18 | scrollTo: -1,
19 | scrollHistory: true,
20 | hashGenerator: function (text, element) {
21 | return element.prop('id');
22 | }
23 | }).data('toc-tocify');
24 |
25 | $("#nav-button").click(function () {
26 | $(".tocify-wrapper").toggleClass('open');
27 | $("#nav-button").toggleClass('open');
28 | return false;
29 | });
30 |
31 | $(".page-wrapper").click(closeToc);
32 | $(".tocify-item").click(closeToc);
33 |
34 | $('ul').prev('li').find('a').each(function (index) {
35 | var that = this;
36 | setTimeout(function () {
37 | var startingClass = ($(that).parent().hasClass('tocify-focus')) ? 'close' : 'open';
38 | $(that).append(
39 | $("").addClass(startingClass)
40 | );
41 | }, 200);
42 |
43 | $(this).click(function () {
44 | $('#toc a span').removeClass('close');
45 | $(this).find('span').first().addClass('close');
46 | });
47 | });
48 | };
49 |
50 | // Hack to make already open sections to start opened,
51 | // instead of displaying an ugly animation
52 | function animate() {
53 | setTimeout(function () {
54 | toc.setOption('showEffectSpeed', 180);
55 | }, 50);
56 | }
57 |
58 | function makeLinks() {
59 | // Append anchor links
60 | $(":header").each(function () {
61 | if ($(this).attr('id')) {
62 | var link = $('').attr('href', '#' + $(this).attr('id'));
63 | $(this).append(link);
64 |
65 | $(this).on('mouseenter',function(){
66 | $(this).find('i.fa-link').css('display', 'inline');
67 | });
68 | $(this).on('mouseleave',function(){
69 | $(this).find('i.fa-link').css('display', 'none');
70 | });
71 | }
72 | });
73 | }
74 |
75 | $(makeToc);
76 | $(animate);
77 |
78 | $(makeLinks);
79 | })(window);
80 |
81 |
--------------------------------------------------------------------------------
/source/includes/_plugin_extending_maintenance.md:
--------------------------------------------------------------------------------
1 | ### Extending Maintenance Cleanup
2 |
3 | ```php
4 | db = $db;
35 | }
36 |
37 | /**
38 | * {@inheritdoc}
39 | */
40 | public static function getSubscribedEvents()
41 | {
42 | return [
43 | CoreEvents::MAINTENANCE_CLEANUP_DATA => ['onDataCleanup', -50]
44 | ];
45 | }
46 |
47 | /**
48 | * @param $isDryRun
49 | * @param $date
50 | *
51 | * @return int
52 | */
53 | public function onDataCleanup (MaintenanceEvent $event)
54 | {
55 | $qb = $this->db->createQueryBuilder()
56 | ->setParameter('date', $event->getDate()->format('Y-m-d H:i:s'));
57 |
58 | if ($event->isDryRun()) {
59 | $rows = (int) $qb->select('count(*) as records')
60 | ->from(MAUTIC_TABLE_PREFIX.'worlds', 'w')
61 | ->where(
62 | $qb->expr()->gte('w.date_added', ':date')
63 | )
64 | ->execute()
65 | ->fetchColumn();
66 | } else {
67 | $rows = (int) $qb->delete(MAUTIC_TABLE_PREFIX.'worlds')
68 | ->where(
69 | $qb->expr()->lte('date_added', ':date')
70 | )
71 | ->execute();
72 | }
73 |
74 | $event->setStat($this->translator->trans('mautic.maintenance.hello_world'), $rows, $qb->getSQL(), $qb->getParameters());
75 | }
76 | }
77 | ```
78 |
79 | To hook into the `mautic:maintenance:cleanup` command, create a listening for the `\Mautic\CoreBundle\CoreEvents::MAINTENANCE_CLEANUP_DATA` event. The event listener should check if data should be deleted or a counted. Use `$event->setStat($key, $affectedRows, $sql, $sqlParameters)` to give feedback to the CLI command. Note that `$sql` and `$sqlParameters` are only used for debugging and shown only in the dev environment.
80 |
81 |
--------------------------------------------------------------------------------
/source/includes/_plugin_misc_translated_entities.md:
--------------------------------------------------------------------------------
1 | ### Implementing Translation Support to Entities
2 |
3 | Mautic has some helper methods with adding support for translated content to an entity.
4 |
5 | #### \Mautic\CoreBundle\Entity\TranslationInterface
6 |
7 | This Entity interface ensures that everything is needed in order for Mautic to handle translations correctly for an entity.
8 |
9 | #### \Mautic\CoreBundle\Entity\TranslationEntityTrait
10 |
11 | This trait provides properties needed to define an Entity's language and relationships to other items. In the Entity's `loadMetadata()` method, be sure to call `$this->addTranslationMetadata()`.
12 |
13 | #### \Mautic\CoreBundle\TranslationModelTrait
14 |
15 | This trait provides the method `getTranslatedEntity()` that will determine the entity to use as the translation based on the `$lead` and/or the `HTTP_ACCEPT_LANGUAGE` header. It also has a `postTranslationEntitySave()` that should be called at the end of the Entity's `saveEntity()` method.
16 |
17 | #### \Mautic\CoreBundle\Doctrine\TranslationMigrationTrait
18 |
19 | To ease the generation of schema to match the Entity, use this trait then execute `$this->addTranslationSchema()`.
20 |
21 | #### Translated Entity Form
22 |
23 | Add a `locale` and `translatedParent` form fields like the code example.
24 |
25 | ```php
26 | em, 'HelloWorldBundle:World');
30 | $builder->add(
31 | $builder->create(
32 | 'translationParent',
33 | 'world_list',
34 | array(
35 | 'label' => 'mautic.core.form.translation_parent',
36 | 'label_attr' => array('class' => 'control-label'),
37 | 'attr' => array(
38 | 'class' => 'form-control',
39 | 'tooltip' => 'mautic.core.form.translation_parent.help'
40 | ),
41 | 'required' => false,
42 | 'multiple' => false,
43 | 'empty_value' => 'mautic.core.form.translation_parent.empty',
44 | 'top_level' => 'translation',
45 | 'ignore_ids' => array((int) $options['data']->getId())
46 | )
47 | )->addModelTransformer($transformer)
48 | );
49 |
50 | $builder->add(
51 | 'language',
52 | 'locale',
53 | array(
54 | 'label' => 'mautic.core.language',
55 | 'label_attr' => array('class' => 'control-label'),
56 | 'attr' => array(
57 | 'class' => 'form-control',
58 | 'tooltip' => 'mautic.page.form.language.help',
59 | ),
60 | 'required' => false,
61 | 'empty_data' => 'en'
62 | )
63 | );
64 | ```
--------------------------------------------------------------------------------
/source/javascripts/app/lang.js:
--------------------------------------------------------------------------------
1 | /*
2 | Copyright 2008-2013 Concur Technologies, Inc.
3 |
4 | Licensed under the Apache License, Version 2.0 (the "License"); you may
5 | not use this file except in compliance with the License. You may obtain
6 | a copy of the License at
7 |
8 | http://www.apache.org/licenses/LICENSE-2.0
9 |
10 | Unless required by applicable law or agreed to in writing, software
11 | distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 | WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 | License for the specific language governing permissions and limitations
14 | under the License.
15 | */
16 | (function (global) {
17 | var languages = [];
18 |
19 | global.setupLanguages = setupLanguages;
20 | global.activateLanguage = activateLanguage;
21 |
22 | function activateLanguage(language) {
23 | if (!language) return;
24 | if (language === "") return;
25 |
26 | $(".lang-selector a").removeClass('active');
27 | $(".lang-selector a[data-language-name='" + language + "']").addClass('active');
28 | for (var i=0; i < languages.length; i++) {
29 | $(".highlight." + languages[i]).parent().hide();
30 | }
31 | $(".highlight." + language).parent().show();
32 |
33 | global.toc.calculateHeights();
34 |
35 | // scroll to the new location of the position
36 | if ($(window.location.hash).get(0)) {
37 | $(window.location.hash).get(0).scrollIntoView(true);
38 | }
39 | }
40 |
41 | // if a button is clicked, add the state to the history
42 | function pushURL(language) {
43 | if (!history) { return; }
44 | var hash = window.location.hash;
45 | if (hash) {
46 | hash = hash.replace(/^#+/, '');
47 | }
48 | history.pushState({}, '', '?' + language + '#' + hash);
49 |
50 | // save language as next default
51 | localStorage.setItem("language", language);
52 | }
53 |
54 | function setupLanguages(l) {
55 | var currentLanguage = l[0];
56 | var defaultLanguage = localStorage.getItem("language");
57 |
58 | languages = l;
59 |
60 | if ((location.search.substr(1) !== "") && (jQuery.inArray(location.search.substr(1), languages)) != -1) {
61 | // the language is in the URL, so use that language!
62 | activateLanguage(location.search.substr(1));
63 |
64 | localStorage.setItem("language", location.search.substr(1));
65 | } else if ((defaultLanguage !== null) && (jQuery.inArray(defaultLanguage, languages) != -1)) {
66 | // the language was the last selected one saved in localstorage, so use that language!
67 | activateLanguage(defaultLanguage);
68 | } else {
69 | // no language selected, so use the default
70 | activateLanguage(languages[0]);
71 | }
72 | }
73 |
74 | // if we click on a language tab, activate that language
75 | $(function() {
76 | $(".lang-selector a").on("click", function() {
77 | var language = $(this).data("language-name");
78 | pushURL(language);
79 | activateLanguage(language);
80 | return false;
81 | });
82 | window.onpopstate = function(event) {
83 | activateLanguage(window.location.search.substr(1));
84 | };
85 | });
86 | })(window);
87 |
--------------------------------------------------------------------------------
/source/includes/_plugin_extending_pages.md:
--------------------------------------------------------------------------------
1 | ### Extending Landing Pages
2 |
3 | ```php
4 | array('onPageBuild', 0),
27 | PageEvents::PAGE_ON_DISPLAY => array('onPageDisplay', 0)
28 | );
29 | }
30 |
31 | /**
32 | * Register the tokens and a custom A/B test winner
33 | *
34 | * @param PageBuilderEvent $event
35 | */
36 | public function onPageBuild(PageBuilderEvent $event)
37 | {
38 | // Add page tokens
39 | $content = $this->templating->render('HelloWorldBundle:SubscribedEvents\PageToken:token.html.php');
40 | $event->addTokenSection('helloworld.token', 'plugin.helloworld.header', $content);
41 |
42 | // Add AB Test Winner Criteria
43 | $event->addAbTestWinnerCriteria(
44 | 'helloworld.planetvisits',
45 | array(
46 | // Label to group by
47 | 'group' => 'plugin.helloworld.header',
48 |
49 | // Label for this specific a/b test winning criteria
50 | 'label' => 'plugin.helloworld.pagetokens.',
51 |
52 | // Static callback function that will be used to determine the winner
53 | 'callback' => '\MauticPlugin\HelloWorldBundle\Helper\AbTestHelper::determinePlanetVisitWinner'
54 | )
55 | );
56 | }
57 |
58 | /**
59 | * Search and replace tokens with content
60 | *
61 | * @param PageSendEvent $event
62 | */
63 | public function onPageDisplay(PageSendEvent $event)
64 | {
65 | // Get content
66 | $content = $event->getContent();
67 |
68 | // Search and replace tokens
69 | $content = str_replace('{hello}', 'world!', $content);
70 |
71 | // Set updated content
72 | $event->setContent($content);
73 | }
74 | }
75 | ```
76 |
77 | There are two way to extend pages: page tokens used to insert dynamic content into a page and a/b test winning criteria . Both leverage the `\Mautic\PageBundle\PageEvents::PAGE_ON_BUILD` event. Read more about [listeners and subscribers](#events).
78 |
79 | #### Page Tokens
80 |
81 | Page tokens are handled exactly the same as [Email Tokens](#page-tokens).
82 |
83 | #### Page A/B Test Winner Criteria
84 |
85 | Custom landing page A/B test winner criteria is handled exactly the same as [page A/B test winner criteria](#page-a/b-test-winner-criteria) with the only differences being that the `callback` function is passed `Mautic\PageBundle\Entity\Page $page` and `Mautic\PageBundle\Entity\Page $parent` instead. Of course `$children` is an ArrayCollection of Page entities as well.
--------------------------------------------------------------------------------
/source/includes/_plugin_services_mail_helper.md:
--------------------------------------------------------------------------------
1 | ### Mail Helper
2 |
3 | ```php
4 | get('mautic.helper.mailer')->getMailer();
6 |
7 | // To address; can use setTo(), addCc(), setCc(), addBcc(), or setBcc() as well
8 | $mailer->addTo($toAddress, $toName);
9 |
10 | // Set a custom from; will use system settings by default
11 | $mailer->setFrom(
12 | $this->user->getEmail(),
13 | $this->user->getFirstName().' '.$this->user->getLastName()
14 | );
15 |
16 | // Set subject
17 | $mailer->setSubject($email['subject']);
18 |
19 | // Set content
20 | $mailer->setBody($content);
21 | $mailer->parsePlainText($content);
22 |
23 | // Optional lead tracking (array)
24 | $mailer->setLead($lead);
25 | $mailer->setIdHash();
26 |
27 | // Send the mail, pass true to dispatch through event listeners (for replacing tokens, etc)
28 | if ($mailer->send(true)) {
29 |
30 | // Optional to create a stat to allow a web view, tracking, etc
31 | $mailer->createLeadEmailStat();
32 | } else {
33 | $errors = $mailer->getErrors();
34 | $failedRecipients = $errors['failures'];
35 | }
36 | ```
37 |
38 | ```php
39 | get('mautic.helper.mailer')->getMailer();
45 | $failed = array();
46 |
47 | $mailer->enableQueue();
48 | foreach ($emailList as $email) {
49 | try {
50 | if (!$mailer->addTo($email['email'], $email['name'])) {
51 | // Clear the errors so it doesn't stop the next send
52 | $mailer->clearErrors();
53 |
54 | $failed[] = $email;
55 |
56 | continue;
57 | }
58 | } catch (BatchQueueMaxException $e) {
59 | // Queue full so flush (send) then try again
60 | if (!$mailer->flushQueue()) {
61 | $errors = $mailer->getErrors();
62 | $failed = array_merge($failed, $errors['failures']);
63 | }
64 |
65 | if (!$mailer->addTo($email['email'], $email['email'], $email['name'])) {
66 | // ...
67 | }
68 | }
69 | }
70 |
71 | // Flush pending
72 | if (!$mailer->flushQueue()) {
73 | // ...
74 | }
75 | ```
76 |
77 | The mail helper can be used to send email, running the content through the event listeners to search/replace tokens, manipulate the content, etc.
78 |
79 | Some transports, such as Mandrill, support tokenized emails for multiple recipients. The mail helper makes it easy to leverage this feature by using it's `queue()` and `flushQueue()` functions in place of `send()`. If sending a batch of emails, it is recommended to use the `queue()` function. Although these classes will still work with using just `send()` for one off emails, if sending a batch of the same email to multiple contacts, enable tokenization/batch mode with `enableQueue()`.
80 |
81 | If using an Email entity (`\Mautic\EmailBundle\Entity\Email`), just pass the Email entity to `$mailer->setEmail($email)` and the subject, body, assets, etc will be extracted and automatically set.
82 |
83 | #### Attachments
84 |
85 | Attachments can be attached to emails by using the `attachFile()` function. You can also attach Mautic assets (`\Mautic\AssetBundle\Entity\Asset`) via `attachAsset()`.
86 |
87 | Refer to the class for more details on available functions.
--------------------------------------------------------------------------------
/source/stylesheets/print.css.scss:
--------------------------------------------------------------------------------
1 | @charset "utf-8";
2 | @import 'normalize';
3 | @import 'compass';
4 | @import 'variables';
5 | @import 'icon-font';
6 |
7 | /*
8 | Copyright 2008-2013 Concur Technologies, Inc.
9 |
10 | Licensed under the Apache License, Version 2.0 (the "License"); you may
11 | not use this file except in compliance with the License. You may obtain
12 | a copy of the License at
13 |
14 | http://www.apache.org/licenses/LICENSE-2.0
15 |
16 | Unless required by applicable law or agreed to in writing, software
17 | distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
18 | WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
19 | License for the specific language governing permissions and limitations
20 | under the License.
21 | */
22 |
23 | $print-color: #999;
24 | $print-color-light: #ccc;
25 | $print-font-size: 12px;
26 |
27 | body {
28 | @extend %default-font;
29 | }
30 |
31 | .tocify, .toc-footer, .lang-selector, .search, #nav-button {
32 | display: none;
33 | }
34 |
35 | .tocify-wrapper>img {
36 | margin: 0 auto;
37 | display: block;
38 | }
39 |
40 | .content {
41 | font-size: 12px;
42 |
43 | pre, code {
44 | @extend %code-font;
45 | @extend %break-words;
46 | border: 1px solid $print-color;
47 | border-radius: 5px;
48 | font-size: 0.8em;
49 | }
50 |
51 | pre {
52 | padding: 1.3em;
53 | }
54 |
55 | code {
56 | padding: 0.2em;
57 | }
58 |
59 | table {
60 | border: 1px solid $print-color;
61 | tr {
62 | border-bottom: 1px solid $print-color;
63 | }
64 | td,th {
65 | padding: 0.7em;
66 | }
67 | }
68 |
69 | p {
70 | line-height: 1.5;
71 | }
72 |
73 | a {
74 | text-decoration: none;
75 | color: #000;
76 | }
77 |
78 | h1 {
79 | @extend %header-font;
80 | font-size: 2.5em;
81 | padding-top: 0.5em;
82 | padding-bottom: 0.5em;
83 | margin-top: 1em;
84 | margin-bottom: $h1-margin-bottom;
85 | border: 2px solid $print-color-light;
86 | border-width: 2px 0;
87 | text-align: center;
88 | }
89 |
90 | h2 {
91 | @extend %header-font;
92 | font-size: 1.8em;
93 | margin-top: 2em;
94 | border-top: 2px solid $print-color-light;
95 | padding-top: 0.8em;
96 | }
97 |
98 | h1+h2, h1+div+h2 {
99 | border-top: none;
100 | padding-top: 0;
101 | margin-top: 0;
102 | }
103 |
104 | h3, h4 {
105 | @extend %header-font;
106 | font-size: 0.8em;
107 | margin-top: 1.5em;
108 | margin-bottom: 0.8em;
109 | text-transform: uppercase;
110 | }
111 |
112 | h5, h6 {
113 | text-transform: uppercase;
114 | }
115 |
116 | aside {
117 | padding: 1em;
118 | border: 1px solid $print-color-light;
119 | border-radius: 5px;
120 | margin-top: 1.5em;
121 | margin-bottom: 1.5em;
122 | line-height: 1.6;
123 | }
124 |
125 | aside:before {
126 | vertical-align: middle;
127 | padding-right: 0.5em;
128 | font-size: 14px;
129 | }
130 |
131 | aside.notice:before {
132 | @extend %icon-info-sign;
133 | }
134 |
135 | aside.warning:before {
136 | @extend %icon-exclamation-sign;
137 | }
138 |
139 | aside.success:before {
140 | @extend %icon-ok-sign;
141 | }
142 | }
--------------------------------------------------------------------------------
/source/includes/_plugin_mvc_models.md:
--------------------------------------------------------------------------------
1 | ### Models
2 |
3 | ```php
4 | mailer;
23 |
24 | $mailer->message->addTo(
25 | $this->factory->getParameter('mailer_from_email')
26 | );
27 |
28 | $this->message->setFrom(
29 | array($data['email'] => $data['name'])
30 | );
31 |
32 | $mailer->message->setSubject($data['subject']);
33 |
34 | $mailer->message->setBody($data['message']);
35 |
36 | $mailer->send();
37 | }
38 | }
39 | ```
40 | Models are used to retrieve and process data between controllers and views. Models aren't required for plugins but, if used, Mautic provides means to easily obtain the model objects and some commonly used methods.
41 |
42 | #### Model Classes
43 |
44 | Model's should be registered as [`model` services](#service-types). The names of these services should match the following nomenclature: `mautic.UNIQUE_BUNDLE_IDENTIFIER.model.MODEL_IDENTIFIER`. `UNIQUE_BUNDLE_IDENTIFIER` can be whatever is desired but must be unique across all Mautic bundles and plugins. `MODEL_IDENTIFIER` just has to be unique for the given bundle. For example, the model example code could be registered as `mautic.helloworld.model.contact`. This allows the helper functions to retrieve model objects to find the correct model service.
45 |
46 | Custom models can extend one of two Mautic base models to leverage some helper functions:
47 |
48 | ##### \Mautic\CoreBundle\Model\AbstractCommonModel
49 |
50 | This is the basic model that mainly provides access to services frequently used with models.
51 |
52 | Property|Service
53 | --------|-------
54 | $this->factory | [Mautic's factory service](#factory-service) - deprecated as of 2.0; use direct dependency injection where possible
55 | $this->em | [Entity manager service](#database)
56 | $this->security | [Mautic's security service](#security)
57 | $this->dispatcher | [Event dispatcher service](#events)
58 | $this->translator | [Translator service](#translator)
59 |
60 | ##### \Mautic\CoreBundle\Model\FormModel
61 |
62 | The FormModel extends AbstractCommonModel and provides a set of helper methods for interacting with entities and repositories. To read more about these methods, refer to the [Database](#database) section.
63 |
64 | #### Getting Model Objects
65 |
66 | ```php
67 | getModel('lead'); // shortcut for lead.lead
71 |
72 | /** @var \Mautic\LeadBundle\Model\ListModel $leadListModel */
73 | $leadListModel = $this->getModel('lead.list');
74 |
75 | /** @var \MauticPlugin\HelloWorldBundle\Model\ContactModel $contactModel */
76 | $contactModel = $this->getModel('helloworld.contact');
77 | ```
78 |
79 | If using a model in another service or model, inject the model service as a dependency. If in a controller, use the `getModel()` helper function.
--------------------------------------------------------------------------------
/source/includes/_plugin_misc_helpers_chartquery.md:
--------------------------------------------------------------------------------
1 | #### ChartQuery and Graphs
2 |
3 | There are several classes available to assist with generating chart data.
4 |
5 | ```php
6 | em->getConnection(), $dateFrom, $dateTo);
12 | $q = $query->prepareTimeDataQuery('lead_points_change_log', 'date_added', $filter);
13 | $data = $query->loadAndBuildTimeData($q);
14 | $chart->setDataset($this->translator->trans('mautic.point.changes'), $data);
15 | $data = $chart->render();
16 | ```
17 |
18 |
19 | ##### ChartQuery
20 |
21 | ChartQuery is a helper class to get the chart data from the database. Instantiate it with the Doctrine connection object, date from and date to. Those dates must be instances of the DateTime class. ChartQuery will automatically guess the time unit (hours, days, weeks, months or years) based on the items between the date range. However, if you want to receive the data from a specific time unit, pass it as the fourth parameter (H, d, W, m, Y).
22 |
23 | ChartQuery also fills in the missing items (if any) which is required to display the data properly in the line chart generated by the [ChartJS](http://chartjs.org).
24 |
25 | ##### LineChart
26 |
27 | LineChart is used in Mautic to display a date/time related data where the time is on the horizontal axis and the values are in the vertical axis. ChartJS' line charts can display multiple datasets in one chart. Instantiate the LineChart with a unit (null for unit guessing), from date, to date (the same as for the ChartQuery) and a date format (null for automatically generated date format).
28 |
29 | All the params you need to instantiate the LineChart are used to generate the labels of the horizontal axis. To add the dataset to the LineChart object, use the `setDataset($label, $data)` method where the label is string and data is an array generated by the ChartQuery. The color of each dataset will be generated automatically.
30 |
31 | Call the `render()` method to get the data prepared for ChartJS.
32 |
33 | ##### PieChart
34 |
35 | A PieChart can be instantiated simply by `new PieChart()`. To add a dataset, use again the `setDataset($label, $value)` method where the label is a string and value is integer.
36 |
37 | Call the `render()` method to get the data prepared for ChartJS.
38 |
39 | ##### BarChart
40 |
41 | BarChart is used to display different variants of the same value where the variants are in the horizontal axis and the value is in vertical axis. To create a bar chart, use `new BarChart($labels)` where labels is an array of all the variants. Each variant can have multiple datasets. To add a dataset, use the `setDataset($label, $data, $order)` method where the label is string, data is array of values for each variant. Order can be used to move the dataset before already created dataset.
42 |
43 | Call the `render()` method to get the data prepared for ChartJS.
44 |
45 |
46 | ```php
47 | render('MauticCoreBundle:Helper:chart.html.php', array('chartData' => $data, 'chartType' => 'line', 'chartHeight' => 300)); ?>
48 | ```
49 |
50 | ##### Frontend
51 |
52 | At the frontend, simply use the prepared chart template, pass in the chart data, the chart type (line/bar/pie) and the chart height. The width is responsive.
53 |
--------------------------------------------------------------------------------
/source/includes/_api_endpoint_themes.md:
--------------------------------------------------------------------------------
1 | ## Themes
2 | This endpoint is useful for working with Mautic themes.
3 |
4 | ```php
5 | newAuth($settings);
11 | $apiUrl = "https://your-mautic.com";
12 | $api = new MauticApi();
13 | $themesApi = $api->newApi("themes", $auth, $apiUrl);
14 | ```
15 |
16 | ### Get theme
17 |
18 | Returns directly the zip file in the response with the `application/zip` header on success or a JSON response body with error messages on fail. The PHP API library will save the zip file to the system temporary directory and provides you with the path.
19 |
20 | ```php
21 | get($themeName);
23 | ```
24 | ```json
25 | {
26 | "file": "/absolute/path/to/the/system/temp/dir/with/the/theme/zip/file"
27 | }
28 | ```
29 |
30 | #### HTTP Request
31 |
32 | `GET /themes/THEME_NAME`
33 |
34 | #### Response
35 |
36 | `Expected Response Code: 200`
37 |
38 | ### Set Temporary File Path
39 |
40 | Changes the default temporary directory where the zip file is created. The directory is created if it does not exist.
41 |
42 | ```php
43 | setTemporaryFilePath("/absolute/path/to/a/different/temp/dir");
45 | $response = $themesApi->get($themeName);
46 | ```
47 | ```json
48 | {
49 | "file": "/absolute/path/to/a/different/temp/dir/zipfile"
50 | }
51 | ```
52 |
53 | ### Get List of themes
54 |
55 | Lists all installed themes with the detailes stored in their config.json files.
56 |
57 | ```php
58 | getList();
60 | ```
61 | ```json
62 | {
63 | "themes": {
64 | "blank": {
65 | "name": "Blank",
66 | "key": "blank",
67 | "config": {
68 | "name": "Blank",
69 | "author": "Mautic team",
70 | "authorUrl": "https:\/\/mautic.org",
71 | "features": [
72 | "page",
73 | "email",
74 | "form"
75 | ]
76 | }
77 | },
78 | ...
79 | }
80 | }
81 | ```
82 |
83 | #### HTTP Request
84 |
85 | `GET /themes`
86 |
87 | #### Response
88 |
89 | `Expected Response Code: 200`
90 |
91 | See JSON code example.
92 |
93 | **Response Properties**
94 |
95 | Name|Type|Description
96 | ----|----|-----------
97 | themes|array|List of installed themes and their configs
98 |
99 | ### Create Theme
100 |
101 | Creates a new theme or updates an existing one (based on the file name) from provided zip file.
102 |
103 | ```php
104 | dirname(__DIR__).'/'.'mytheme.zip' // Must be a path to an existing file
107 | );
108 |
109 | $response = $themeApi->create($data);
110 | ```
111 | The file is sent via regular POST files array like a browser sends it during file upload.
112 |
113 | #### HTTP Request
114 |
115 | `POST /themes/new`
116 |
117 | #### Response
118 |
119 | `Expected Response Code: 200`
120 | ```json
121 | {
122 | "success": true
123 | }
124 | ```
125 |
126 | ### Delete File
127 | ```php
128 | delete($themeName);
130 | ```
131 | Delete a theme. The stock themes cannot be deleted
132 |
133 | #### HTTP Request
134 |
135 | `DELETE /themes/THEME_NAME/delete`
136 |
137 | #### Response
138 |
139 | `Expected Response Code: 200`
140 | ```json
141 | {
142 | "success": true
143 | }
144 | ```
145 |
--------------------------------------------------------------------------------
/source/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Mautic Developer Documentation
3 |
4 | language_tabs:
5 | - php
6 | - json
7 |
8 | toc_footers:
9 | - Download Mautic source
10 | - Documentation powered by Slate
11 |
12 | includes:
13 | - introduction
14 | - cache
15 | - plugin_intro
16 | - plugin_migrations
17 | - plugin_migrations_1.2
18 | - plugin_migrations_2.0
19 | - plugin_migrations_3.0
20 | - plugin_structure
21 | - plugin_install
22 | - plugin_config
23 | - plugin_translations
24 | - plugin_mvc
25 | - plugin_mvc_controllers
26 | - plugin_mvc_models
27 | - plugin_mvc_views
28 | - plugin_services
29 | - plugin_services_factory
30 | - plugin_services_users
31 | - plugin_services_security
32 | - plugin_services_translator
33 | - plugin_services_router
34 | - plugin_services_request
35 | - plugin_services_session
36 | - plugin_services_database
37 | - plugin_services_parameters
38 | - plugin_services_event_dispatcher
39 | - plugin_services_paths_helper
40 | - plugin_services_ip_lookup_helper
41 | - plugin_services_plugin_config_helper
42 | - plugin_services_cookie_helper
43 | - plugin_services_mail_helper
44 | - plugin_services_model_factory
45 | - plugin_database
46 | - plugin_permissions
47 | - plugin_configuration
48 | - plugin_integrations
49 | - plugin_integrations_migrations
50 | - plugin_integrations_authentication
51 | - plugin_integrations_configuration
52 | - plugin_integrations_sync
53 | - plugin_integrations_builder
54 | - plugin_manipulating_contacts
55 | - plugin_extending_intro
56 | - plugin_extending_api
57 | - plugin_extending_broadcasts
58 | - plugin_extending_campaigns
59 | - plugin_extending_categories
60 | - plugin_extending_contacts
61 | - plugin_extending_emails
62 | - plugin_extending_forms
63 | - plugin_extending_integrations
64 | - plugin_extending_maintenance
65 | - plugin_extending_pages
66 | - plugin_extending_points
67 | - plugin_extending_reports
68 | - plugin_extending_webhooks
69 | - plugin_extending_ui
70 | - plugin_misc
71 | - plugin_misc_flashes
72 | - plugin_misc_helpers
73 | - plugin_misc_helpers_input
74 | - plugin_misc_helpers_datetime
75 | - plugin_misc_helpers_chartquery
76 | - plugin_misc_commands
77 | - plugin_misc_forms
78 | - plugin_misc_events
79 | - plugin_misc_translated_entities.md
80 | - plugin_misc_variant_entities.md
81 | - marketplace.md
82 | - themes
83 | - api_intro
84 | - api_authorization
85 | - api_authorization_oauth1a
86 | - api_authorization_oauth2
87 | - api_authorization_basic
88 | - api_rate_limiter
89 | - api_libraries
90 | - api_endpoints
91 | - api_endpoint_assets
92 | - api_endpoint_campaigns
93 | - api_endpoint_categories
94 | - api_endpoint_companies
95 | - api_endpoint_contacts
96 | - api_endpoint_data
97 | - api_endpoint_dynamic_contents
98 | - api_endpoint_emails
99 | - api_endpoint_fields
100 | - api_endpoint_files
101 | - api_endpoint_forms
102 | - api_endpoint_messages
103 | - api_endpoint_notes
104 | - api_endpoint_notifications
105 | - api_endpoint_pages
106 | - api_endpoint_point_actions
107 | - api_endpoint_point_triggers
108 | - api_endpoint_reports
109 | - api_endpoint_roles
110 | - api_endpoint_segments
111 | - api_endpoint_smses
112 | - api_endpoint_stages
113 | - api_endpoint_stats
114 | - api_endpoint_tags
115 | - api_endpoint_themes
116 | - api_endpoint_tweets
117 | - api_endpoint_users
118 | - api_endpoint_webhooks
119 | - webhooks
120 | - mauticjs_api_intro
121 | - mauticjs_api_reference
122 |
123 | search: true
124 | ---
125 |
--------------------------------------------------------------------------------
/source/includes/_api_endpoint_files.md:
--------------------------------------------------------------------------------
1 | ## Files
2 | This endpoint is useful for working with files of images and assets.
3 |
4 | _Note: Assets doesn't have nor support subdirectories._
5 |
6 | ```php
7 | newAuth($settings);
13 | $apiUrl = "https://your-mautic.com";
14 | $api = new MauticApi();
15 | $filesApi = $api->newApi("files", $auth, $apiUrl);
16 | ```
17 |
18 | ### Get List of files
19 | ```php
20 | getList();
24 |
25 | // Get list of some sub-directory (flags in this case) of media/images:
26 | $filesApi->setFolder('images/flags');
27 | $files = $filesApi->getList();
28 |
29 | // Get list of root media/files directory where the asset files are stored:
30 | $files = $filesApi->setFolder('assets');
31 | $files = $filesApi->getList();
32 | ```
33 | ```json
34 | {
35 | "files":{
36 | "3":"0b0f20185251d1c0cd5ff17950213fc9.png",
37 | "4":"0f530efdf837d3005bd2ab81cc30e878.jpeg",
38 | "5":"162a694f4101cb06c27c0a0699bd87c4.png",
39 | "6":"16ada2e2ecfa3f1d8cbb5d633f0bd8c6.png",
40 | ...
41 | }
42 | }
43 | ```
44 |
45 | #### HTTP Request
46 |
47 | `GET /files/images` to get root images directory
48 | `GET /files/images?subdir=flags` to get images/flags directory
49 | `GET /files/assets` to get root assets directory
50 |
51 | #### Response
52 |
53 | `Expected Response Code: 200`
54 |
55 | See JSON code example.
56 |
57 | **Response Properties**
58 |
59 | Name|Type|Description
60 | ----|----|-----------
61 | files|array|List of requested files and directories
62 |
63 | ### Create File
64 | ```php
65 | dirname(__DIR__).'/'.'mauticlogo.png' // Must be a path to an existing file
68 | );
69 |
70 | // Create a file in root media/images directory:
71 | $response = $fileApi->create($data);
72 |
73 | // Create a file in some sub-directory (flags in this case) of media/images:
74 | $filesApi->setFolder('images/flags');
75 | $response = $fileApi->create($data);
76 |
77 | // Create a file in media/files directory where the asset files are stored:
78 | $files = $filesApi->setFolder('assets');
79 | $response = $fileApi->create($data);
80 | ```
81 | Creates a file. The file is sent via regular POST files array like a browser sends it during file upload.
82 |
83 | #### HTTP Request
84 |
85 | `POST /files/DIR/new`
86 |
87 | #### Response
88 |
89 | `Expected Response Code: 200`
90 | ```json
91 | {
92 | "file":{
93 | "link":"http:\/\/yourmautic\/media\/images\/2b912b934dd2a4da49a226d0bf68bfea.png",
94 | "name":"2b912b934dd2a4da49a226d0bf68bfea.png"
95 | }
96 | }
97 | ```
98 |
99 | **Response Properties**
100 |
101 | Name|Type|Description
102 | ----|----|-----------
103 | link|string|Appears only for files in image directory, not for assets
104 | name|string|File name of newly created file
105 |
106 | ### Delete File
107 | ```php
108 | delete($fileName);
111 |
112 | // Delete a file from some sub-directory (flags in this case) of media/images:
113 | $filesApi->setFolder('images/flags');
114 | $response = $fileApi->delete($fileName);
115 |
116 | // Delete a file from media/files directory where the asset files are stored:
117 | $files = $filesApi->setFolder('assets');
118 | $response = $fileApi->delete($fileName);
119 | ```
120 | Delete a file.
121 |
122 | #### HTTP Request
123 |
124 | `DELETE /files/DIR/FILE/delete`
125 |
126 | #### Response
127 |
128 | `Expected Response Code: 200`
129 | ```json
130 | {
131 | "success": true
132 | }
133 | ```
134 |
--------------------------------------------------------------------------------
/source/includes/_plugin_translations.md:
--------------------------------------------------------------------------------
1 | ## Translations
2 |
3 | Mautic uses INI files for translations.
4 |
5 | HelloWorldBundle/