CiviCRM Community Forums (archive)

Hi everyone,

Okay I've spent most of today reading the documentation, using the api explorer and trying to understand some of it.

I have to give some indication soon to the rest of the team about whether the project is within my abilities. Also - for me this is a small job that I only want to spend a few  days on - or could spend longer on if necessary - but I have my own Windows C programs to develop which is the main thing I do - so don't want to spend like many weeks on this. Also for them it is a small but important detail in a large project, so they can't really justify putting so much time into it either or budgeting for it.

I tried to understand the buildform hook - but that was way beyond me because I didn't know how the $form variable worked, what you should change in it, e.g. how you could use it to add a new column and to populate that column with the custom data, just didn't know how to get started, no ideas at all even after reading the documentation about what to do - except of course, that you need to check the form name to make sure the hook is used for the right form but no idea what to do after that.

Anyway I thought that a simple bit of code to get started to understand how the variables work etc. would be to do an enumeration of the activities as an ordered list and just add that code to the Selector.tpl - and then if I acheived that - to see if I could get the custom data as well for each id. I.e. as you often do while learning an environment or language, try a simple project, one you can understand in its entirety and hope to complete in a few hours at most.

Probably this is something I will need to do at some point during the project, e.g. in the code within the buildForm hook.

Also I thought there might be a possibility that I could achieve something useful using a minimal amount of Civicrm code and a lot of javascript and html to duplicate stuff someone experienced in Civicrm would do using the hooks and changing values in the returned $form etc. Maybe I could "roll my own activities table" in some way. And if not, by attempting to do it I could learn more about how Civicrm works.

So - this code worked to print out an ordered list of activity subjects and ids, and to show the date and time for each one:

<h4>Activities</h4>
<ul>
{crmAPI var="ActivityS" entity="Activity" action="get" q="civicrm/ajax/rest" version="3" }
{foreach from=$ActivityS.values item=Activity}
<li>Activity id: {$Activity.id} <br>
Subject: {$Activity.subject} <br>
Date and time: {$Activity.activity_date_time}
<br>----
 </li>
{/foreach}
</ul>

It's sorted by id. But using the activity_date_time field and a bit of javascript you should be able to sort it by date easily enough. The rest of the columns show ids, but by listing e.g. all the contacts and matching their ids with the contact_ids for the activities you could loop around and find out which contact name went with which activity etc. and so with enough work just duplicate the activity table in javascript and html.

So then I tried to find the custom data and so (within the same foreach loop as above) tried using:

{assign var=activityId value=$Activity.id}
 activityId {$activityId}
 {  $activityWithCustomData = array();
  $activityWithCustomData=_civicrm_activity_get($activityId,true);
  }

It seemed to me - mainly guessing, from the variable name and also looking at the code for the routine itself - that _civicrm_activity_get with  $returnCustom = true should return a complete list of all the fields for the activity including the custom data.

But - beyond knowing that the return value of the API functions is always an array, the documentation didn't seem to give me much information about how to interpret that array and extract information from it. So I was stuck at that point - I gather you have to use some string variable as the array argument such as  $activityWithCustomData['example'] but how you find the right string to put there to get the information you need I haven't quite figured out yet.

I also found the $viewCustomData variable which by its name looked promising as likely to be some kind of an interface you could use to extract custom data. But in the example code

{assign var=eventValueId value=$event.id}
{$viewCustomData.group_id.$eventValueId.fields.field_id.field_value}

I wondered if when used within the Activities form, the same code would work using
 {assign var=activityId value=$Activity.id}
But didn't get anywhere with that approach not yet anyway.

I tried searches for forum discussions or example code using those variables and didn't find anything and I can't make much from the api explorer, so much of it for me at this stage is just guesswork based on the variable names and what it seems likely that they do.

I do appreciate that a lot of work has gone into the api explorer and the project so far, the api explorer particularly is a neat bit of work. But there isn't enough documentation or enough by way of example source code for me to get very far with it myself. I will need a fair amount of help I think.

I wondered if I could get somewhere by learning just a small amount of civicrm, and doing the rest with javascript and html. But after the difficulties trying to figure out how to get the custom data, not sure about that either.

Do you think I could get anywhere with this project with either approach?

Also after spending two or three hours on it today trying various things - I would be interested to know what is the correct way to get the custom data for an activity given its id - even if I don't follow up this project any further, would like to know what the right answer was there (or is it not possible so I was following a false track there?).

Also, even if perhaps it is beyond me at this stage, I wonder if it may help to share my experiences here as a way to improve the documentation in the future - to understand some of the issues newbies may face?

I'm reasonably quick at picking up coding concepts, so if I find this difficult to get started with, I think probably quite a few other developers would be in the same situation. So if some of this stuff was documented in more detail then maybe you would get more coders working with civicrm.

Particularly if you are going to code hooks, you need documentation and code examples to show how the $form variable is used, and what its various elements mean. If the project has an interface for custom data, such as $viewCustomData or _civicrm_activity_get then again some documentation of how those work is needed. And the code itself - though it does use probably carefully thought out variable names, has almost no inline comments at all. E.g. a few carefully chosen comments within the buildContactActivities(..) function in the Selector.tpl and a paragraph or two of comments at the top of the page to say a bit about what its function is and how you can customise it or use it would make a big difference to a newbie reading it.

This is not particular to civicrm. Much of the open source projects I've come across is rather sparsely commented and documented. And I don't mean this as a criticism at all, just a suggestion for future improvement if you want to make it easier for other developers to customize civicrm at the code level.

I hope this is helpful.

Thanks,

Hi Everyone,

I gave up on this because of lack of documentation and comments. But the team are continuing with the project, they found other ways of dealing with it.

Do please consider adding comments to the code and more documentation and code samples for future developers who want to work with civicrm.

I don't know how you manage to maintain it - the code is clearly good quality but I don't understand how you manage to keep it maintained yourself without good comments in the code. E.g. how do you write your own hooks when the $form variable isn't documented anywhere? Or how do you deal with the situation if you want to add new functionality to the $form variable? Or if you want to edit Activity.php or Selector.php yourself - do you not require at least many minutes of looking at the code to try to remember what it does before you can do anything? If not now, with absolutely no code comments at all in the page, you will surely need to do so in the future a few years down the line when you forget how it all worked.

Clearly you have found ways to do that. But if you spend some time on documentation and inline comments - it's amazing how that can increase productivity. The extra time spent writing good documentation and comments will pay itself back many times over not just with fewer questions from baffled users, but also with your own coding also, easier to maintain and add new features.

A google search for how to comment your code turns up lots of material on it, e.g. this page (which I just added a couple of tips to today):

13 tips to comment your code

Self commenting code is great, but it is only a part of the picture.

Robert