Developer Training

Customizing OroCRM

Developer Training

Goals- Overview of OroCRM customization

techniques- Demonstrate implementation of customer

requirements - Share best practices

Developer Training

Customization requirements- Account should be accessible from top level

menu- Edit B2bCustomer details from Account

page- Add invoice entity and link it to the Account- Bypass the datetime setting automatically

for Contact, if it’s already set- Add employee_count to Account

Developer Training

Introduction

In general, the same customization methods applied to OroCRM, as to raw Symfony application.

These includes: overriding controllers, views, services. Though some OroCRM specific differences exist.

Developer Training

Manually Auto Generate

- create directory structure app/console generate:bundle- add bundle class

Clear cache afterwards:app/console cache:clear

Adding new bundleNew bundle

Developer Training

Minimal structureBundle folder AcmeBundle, located in:src/Scope/Bundle, where Scope - company, dep., etcAcmeBundle- Resources

- config- oro

- bundles.yml - register your bundle in Oro way- ScopeAcmeBundle.php

Adding new bundle manuallyNew bundle

Developer Training

app/console generate:bundle

--namespace=Acme/DemoBundle --dir=src [--bundle-name=...] --no-interaction

Adding new bundle Symfony wayNew bundle

Developer Training

How it differs from Symfony1. Bundle registration

Resources/config/oro/bundles.ymlinstead of

automatic/manual registering in AppKernel

2. Routes registrationResources/config/oro/routing.yml

instead ofautomatic/manual registering app/config/routing.yml

Adding new bundle the Oro wayNew bundle

Developer Training

The bigger priority number, the later bundle will be loaded.

Suggested priority for custom bundles is >= 200For overriding existing - more than parent.

PrioritiesNew bundle

Developer Training

Manually Auto Generate- create entity class app/console generate:doctrine:entity- describe mapping app/console generate:doctrine:crud

for each entity Entity should already exists before crud

- with annotations Note: Symfony generated

- with yaml/xml views and controllerscould not be used as is.

+ create controllers+ add views and run migration

Creating entity and basic CRUDNew bundle

Developer Training

- Data migrations (Fixtures)- AcmeBundle/Migrations/Data/ORM

- Schema migrations- AcmeBundle/Migrations/Schema/v1_0 (v2_2, v1_0_2, etc)

- AcmeBundle/Migrations/Schema/AcmeBundleInstallercovers state after some migration (e.g. v1_3) using getMigrationVersion method.

Add migrationNew bundle > Creating entity and basic CRUD

Developer Training

• Show queries to update schemadoctrine:schema:update --dump-sql

• Update it by running these SQL queriesdoctrine:schema:update --force or manually

• Use command to get generated installer codeoro:migration:dump --bundle=AcmeDemoBundlesupports --plain-sql optionAcmeDemoBundle/Migrations/Schema/AcmeDemoBundleInstaller

• Drop entities created manually by SQL

• Run app/console oro:platform:update --force

Add migrationNew bundle > Creating entity and basic CRUD

Developer Training

Basic CRUD ControllerBasic CRUD is common across all Oro platform controllers.

What do we need:• Basic controller actions: list, view and update• REST API controller to handle delete• Form type and form API type• Form handler• Routing definition• ApiManager

New bundle > CRUD

Developer Training

Basic CRUD ControllerSteps:• Actions: create, update, index and view• Name routes and acl resources in annotations• Form type, form and form handler as a service• Repeat previous step for API form type, API form and

API form handler• Form handler and API form handler as a service• Register ApiEntityManager as your own service with

entity class name• Define titles in navigation.yml• Don’t forget to add translations

New bundle > CRUD

Developer Training

Routing

AcmeBundle/Resources/config/oro/routing.yml- define regular controller- add definition for API controller- app/console router:debug

New bundle > CRUD

Developer Training

Filling the gapsNow we are able to fill missing parts in our controllers:

Controller use form handler to manage form configured with form type.API Controller use ApiManager to work with entity.

New bundle > CRUD

Developer Training

Filling the gaps

Nextproceed with datagrid definition

using services names, we got at previous step.

New bundle > CRUD

Developer Training

List (index), bare minimum• define list grid with datagrid.yml• extend OroUIBundle:actions:index.html.twig• define gridName (grid definition should

already exists) and pageTitle• add nav button block

ViewsNew bundle > CRUD

Developer Training

Create/Update• extend OroUIBundle:actions:update.html.twig• use oro_title_set command to set title• define blocks: navButtons, pageHeader,

content_data

ViewsNew bundle > CRUD

Developer Training

View• extend OroUIBundle:actions:view.html.twig• use oro_title_set command to set title• main blocks: breadcrumbs, content_data• content widget - reusable block

ViewsNew bundle > CRUD

Developer Training

Each bundle can override another one.If multiple bundles overriding the same one - the last

loaded will win.

AcmeDemoBundle::gerParent() should return short alias of parent bundle, e.g.: OroCRMAccount.

Overriding existing bundle

Developer Training

Use services definition file services.yml (.xml, .php)

- change class name to point to own service- extend custom service from origin

Overriding serviceOverriding existing bundle

Developer Training

Defined in navigation.ymlCustomizations:

- add menu items to existing or new top level item- hide- move existing item

These could be done in the navigation.yml.But in case of menu items are event-driven (e.g. Sales menu) - event listeners or menu builders are the only choice.

Customizing app menuOverriding existing bundle

Developer Training

oro:navigation:initis your friend

(when you change/add titles in navigation.yml)

Customizing app menuOverriding existing bundle

Developer Training

Two types of entities:- regular entity

- Doctrine DBAL Schema to describe changes- change entity manually

- extended entity- Doctrine DBAL Schema- ‘extend’ configuration- automatically generated code

Migrations are used to add or change fields in existing entities.

Add fields to existing entitiesOverriding existing bundle

Developer Training

Order of the migrationOrderedMigrationInterfaceManage order within the same version.

ExtendEntity migrationExtendExtensionAwareInterfaceInject Extend migration extension

Add fields to existing entitiesOverriding existing bundle

Developer Training

Requirements• The base entity must be Extended entity• target entity must be at least Configurable

Configurable entity defined by annotation:Oro\Bundle\EntityConfigBundle\Metadata\Annotation\Config

Extend relationsOverriding existing bundle

Developer Training

Forms override:- using Symfony form inheritance (Form::getParent)- form service class name override + class extend- form extension

Overriding forms and validationOverriding existing bundle

Developer Training

Overriding forms and validation

How to change validation rules?- Define own validation group- Form type guesser

Possible only if form item defined in builder without type

Overriding existing bundle

Developer Training

Same controller class name, same folders structure.

Depending on what is registered in the parent bundle.As one resource - directory Controller- copy-paste all routes definitions- or use Oro way with ! sign

As one resource for each Controller- nothing, works as is

Overriding controllers and routesOverriding existing bundle

Developer Training

Put view (Twig template) in the same directory structure in child bundle, as it’s in parent.

“!” sign could be used with short bundle name syntax,to refer to blocks from parent bundle.

e.g. !@OroCRMAccountBundle:Account:view.twig.htmlwill refer to original template, not overridden.

Overriding views, adding placeholdersOverriding existing bundle

Developer Training

RequireJS configuration: requirejs.ymlMapping should be used to set overrides.

In overridden file - define module with parent module as dependency and override or add methods to it.

JS modules customizationOverriding existing bundle

Developer Training

• New entity• New fields to existing entity• CRUD for new entity• Overridden controller for existing• Routes override• Overridden view and placeholder usage• Form and validation customizations• JS modules extending

Summary

Developer Training

Q & A

Quality Control