Publicat
2009-07-11 02:38
You might want to display more information that those that are assigned by default in the template. My goal was to have a simple way of retrieving more information from civicrm than the ones available in the template, without having to modify the php code .
For instance, I used it to display all the employees of an organisation from the profile that displays the organisation, or to display a list ofother contacts that live in the same country than the contact you're viewing.
In London in the last training, we discussed about displaying the activities directly in the contact summary tab for instance.
The general idea is to be able to use any api method to fetch the content and assign it to a regular smarty variable, so it can then be templated and display how you want it.
It simply introduce a new function in the template, "crmAPI". I'm assuming in the rest of this post that you know already where are stored the templates, how to identify the one you want to modify and have a basic knowledge of smarty.
The extra params allow to filter, for instance only the individual contacts in France, and return only the sort_name and the email.
If you are familiar with civicrm api v2, it will be fairly straightforward to use and fetch about any type of content existing in civicrm and display it where you want. From anywhere within your template, simply call:
{crmAPI entity="nameobject" method="namemethod" var="namevariable" extraparam1="aa" extraparam2="bb"}
- entity is the content you want to fetch, eg. "contact", "activity", "contribution"...
- method is get, search, search_count (it shouldn't be a method that modify the entity, only to fetch data)
- var is the name of the smarty variable you want to assign the result to (eg the list of contacts)
- extraparams (optional) all the other parameters (as many as you want) are simply used directly as the "params" to the api. cf. the example below
- return (optional). The convention to define the return attributes (return.sort_name return.country...) doesn't work with smarty and is replaced by return="attribute1,attribute2,attribute3.."
For instance, is you want to display a list of contacts
{crmAPI entity='contact' action="search" var="contacts"}
<ul>
{foreach from=$contacts item=contact}
<li id="contact_{$contact.contact_id}">{$contact.sort_name}</li>
{/foreach}
</ul>
{crmAPI entity='contact' action="search" var="contacts" country="France" contact_type="Individual" return ="sort_name,email"}
CiviCRM version
This is implemented in the trunk (2.3), but you can backport it to 2.2 by copying the file CRM/Core/Smarty/plugins/function.crmAPI.php
Comments
This is cool in that previously you'd have to do this in two steps with a form alter hook. However it does break the rules of separation between data retrieval and data display.
Hi,
Most of the CMS use a similar approach where you can fetch content from within the template. From a theoretical point of view, the big and important separation is between the application logic and the presentation. the new function does respect that and only assign more variables. That's the template's job to display them.
X+
I can see heaps of potential in this.
I understand the comments about separating the functionality but when you are customising CiviCRM it seems best to try to avoid any changes to the php files if at all possible so being able to do stuff in the tpls is great.
keeping with the convention of how other functions / modifiers are named
Thx
X-
are custom fields retrieved with the corresponding entity? I'm trying this method out for the first time, trying to include some custom fields for groups in the dashboard block. not sure if i'm not implementing correctly, or if custom fields are not included in the api.
This works fine. Sample code:
{crmAPI entity='event' action="search" var="thisevent" id=$event.id return="custom_96,custom_48"}
Hershel
Sometimes you use "method" and sometimes you use "action" in this post. "Action" seems to be the correct one.