CRM Core UI Conventions

CRM Core does not aim to be a CRM system on its own, so much as a tool for building CRM functionality in a Drupal site. This means someone could be looking to build a site just for managing contact relationships, or looking to build some CRM-style functionality in a site with an existing front end that allows interaction with contacts.

To this end, the developers made no assumptions about the UI except for the fact it needs to work with themes that ship with Drupal - it's left open so that site builders can define the UI elements that make the most sense in their use case.

This is both a benefit and a drawback to people developing for CRM Core. When designing a new module, feature or component, it is important to consider the fact that the UI is not static and people will use your code in different ways. Nothing is more frustrating than a link that displays in the wrong place and can't be turned off, just as nothing is more challenging than looking for administrative tools that are not where you would expect them to be.

CRM Core provides a number of UI elements that developers should be aware of. This list deals with the items themselves along with best practices for how to work with them.

Reserved Paths and the CRM Section

All of the paths to content for CRM Core are stored under a path starting with crm-core. Any time a user is accessing a contact, activity, relationship, or screen for managing them, that user will be accessing them under this path.

The developers for CRM Core put the crm-core path in place for a reason. The needs of users working with contacts are very different from the needs of someone working with the front end of a site, or even someone looking to administer Drupal. For instance, if someone is working with contacts, that person will probably not need to see a list of links to the about us section of your website, or links to configure the modules that are installed. That person will likely need to be able to see links to search contacts, create new activities, and the like. This approach addresses this need.

The CRM section of your site is any page loaded through a URL with a path beginning with crm-core. This path can be used reliably in theming or as a basis for triggering contexts. It is the basic tool that is in place for controlling the user interface around contact management.

When creating a module or a feature, any paths for working with contacts or contact information should start with crm-core. This guarantees you or anyone working with your module will be able to use interface elements specific to the CRM section.

You can use paths as a way to control where content appears in the CRM section of your site. There are a number of reserved paths in place to provide developers with intuitive, predictable ways to modify the overall navigation structure. These include the following:

• Contacts: crm-core/contact, crm-core/contacts
• Reports: crm-core/reports
• Dashboard: crm-core, crm-core/dashboard
• Activities: crm-core/contact/%contact-id/activity/%activity-id, crm-core/activity/%activity-id,
• Relationships: crm-core/contact/%contact-id/relationships/%relationship-id, crm-core/relationships/%relationship-id
• Administration: admin/structure/crm-core, admin/config/crm-core

Working within this structure provides advantages to you and anyone who might be using your modules. You can use these paths to reliably control the placement of links within the CRM Core UI regardless of how someone has configured their own site.

Here are some examples of how someone might want to create paths to various screens within the foo module:

• Registering a new top level element (to appear next to dashboard / contacts / reports): crm-core/foo
• Registering a new tab to appear on a contact page: crm-core/contact/%contact-id/foo
• Registering a new report: crm-core/reports/foo/%report-callback
• Registering a new tab to appear on the activities screen: crm-core/contact/%contact-id/activities/foo

CRM Core Menu and CRM Core Admin Menu

CRM Core Menu and CRM Core Admin Menu are provided with CRM Core to provide site administrators with convenient access to global navigation and administrative options within CRM Core itself. They are present in every installation of the module and can be used as a place to register common navigation options by module and feature developers.

This is no guarantee a site administrator would use these menus, bu CRM Core does provide some support for making them useful in the interface. The CRM Core settings page provides controls allowing site builders to replace the primary links in the CRM Core section with links from the CRM Core Menu, for instance, and there are blocks for both of these menus available by default.

When working with these menus, it is important to consider the needs of users. It's fine to register a link for either of these menus, so long as it does what it is supposed to. If your module or feature requires some level of configuration before these links will do something, consider writing code that allows them to appear conditionally.

For instance, in the CRM Core settings page, site builders have an option to enable a dashboard for CRM Core. When a dashboard is configured for the site, a link to the dashboard will appear in the CRM Core Menu. When there is not a dashboard configured for the site, this link disappears. All links to the dashboard will redirect users to the CRM Core Contacts page instead. There are some good examples of how to do this in the CRM Core UI module.

admin/structure/crm-core

Whenever your module or feature provides options for controlling the structure for how content is stored, considering registering it under the path admin/structure/crm-core or one very similar. This will ensure users will know where to find the administrative page without too much trouble.

Some examples of how this is used in CRM Core and other modules:

• CRM Core uses this page to allow administrators to configure contact, activity and relationship types. It is where all links for fieldable entities will be stored.
• CRM Core Profile uses a separate path for accessing its administrative screens: admin/structure/crm-core-profile. This separates out the structure screens because it is used for a very different purpose in the operations of CRM Core.

admin/config/crm-core

Whenever your module or feature provides a settings screen for working with the CRM Core system itself, considering registering it under the path admin/config/crm-core or one very similar. This will ensure users will know where to find options for configuring your module without needing to search the admin screens.

Some examples of how this is used in CRM Core and other modules:

• CRM Core uses this page to allow administrators to configure the UI for CRM Core and how contact records are linked with user records.