Developer Documentation issueshttps://lab.civicrm.org/documentation/docs/dev/-/issues2024-02-27T20:42:57Zhttps://lab.civicrm.org/documentation/docs/dev/-/issues/893Update Settings documentation to be slightly more clear2024-02-27T20:42:57ZshaneonabikeUpdate Settings documentation to be slightly more clearHey folks,
During our CiviCamp I got confused on the settings documentation so I wanted to do the following
* Provide an example of a setting that uses an Option Group
* Clarify the \`\`\`pseudoconstant\`\`\` section for the optiongrou...Hey folks,
During our CiviCamp I got confused on the settings documentation so I wanted to do the following
* Provide an example of a setting that uses an Option Group
* Clarify the \`\`\`pseudoconstant\`\`\` section for the optiongroup setting
Maybe it was just me that was confused, but I think more examples or my mods might make it clearer?https://lab.civicrm.org/documentation/docs/dev/-/issues/867Testing core PRs on client data2023-12-12T18:34:45ZMichael McAndrewTesting core PRs on client data_Here is a little write up I did on testing core PRs on client data for our own docs. I couldn't quite work out the best place for it in the developer guide but wanted to create an issue in case it is more widely useful and we can find a..._Here is a little write up I did on testing core PRs on client data for our own docs. I couldn't quite work out the best place for it in the developer guide but wanted to create an issue in case it is more widely useful and we can find a place for it._
From time to time, we might want to test out a feature in an upcoming release of CiviCRM on a real client site. Maybe the core team is developing a new feature for us. Or someone has submitted a patch that we are also interested in.
If you know the PR, you can download a patch suitable to applying to CiviCRM as follows:
`wget https://patch-diff.githubusercontent.com/raw/civicrm/civicrm-core/pull/<PATCH_NUMBER>.patch`
Then from the repo of the site that you want to patch use `git am` to apply the patch. Use the `--directory` flag to specify the path to CiviCRM. Something like the following should work:
`git am --directory=src/sites/all/modules/civicrm ~/<PATCH_NUMBER>.patch`
If the patch relies on other commits that have been merged into master but not yet released, you might want to upgrade to the most recent 'nightly' build. You can find nightlies here: https://download.civicrm.org/latest/https://lab.civicrm.org/documentation/docs/dev/-/issues/870learn.civi.be refused to connect2023-12-03T17:39:52Zcolemanwlearn.civi.be refused to connect![image](/uploads/9d3ac2d53c4d794b8eebc8f37b3ea354/image.png)![image](/uploads/9d3ac2d53c4d794b8eebc8f37b3ea354/image.png)ErikHommelErikHommelhttps://lab.civicrm.org/documentation/docs/dev/-/issues/880Document best practices for how to handle E_NOTICES/WARNINGS2023-11-15T23:10:58ZDaveDDocument best practices for how to handle E_NOTICES/WARNINGSThere's been a lot of PRs the last year that fix php notices but doing it in new and wonderful ways. There's https://docs.civicrm.org/dev/en/latest/security/outputs/#escape-by-default and the general issue in https://lab.civicrm.org/dev/...There's been a lot of PRs the last year that fix php notices but doing it in new and wonderful ways. There's https://docs.civicrm.org/dev/en/latest/security/outputs/#escape-by-default and the general issue in https://lab.civicrm.org/dev/core/-/issues/1328 but feels like it needs more guidelines.
It's pretty draft right now and just looking for some place to put it so dumping in this ticket.
In smarty templates:
----
* isset() doesn't work with CIVICRM_SMARTY_DEFAULT_ESCAPE because the target gets converted to an expression which isn't allowed with isset(). You can see this in regular php or with escape turned off if you do something like `{if isset(is_array($foo) ? $foo.bar : $foo)}`
* empty() doesn't work with CIVICRM_SMARTY_DEFAULT_ESCAPE because the target gets evaluated by smarty/php before being sent to empty(), so you still get the error.
* array_key_exists works, but:
* Only works on arrays (duh)
* Has the same limitation as empty() because the expressions involved will be evaluated first, e.g. `{if array_key_exists('bar', $form.foo)}` will still give the error if the `foo` element of `$form` does not exist.
But even before all that, what needs to be considered is what the error is really about and the difference between the variations when $x is a falsey value. For example:
* You don't want to silence when it's telling you that the variable name is a typo. This is trickier when it's a variable variable, like `$form.$field`.
* Or when you're expecting it to be there, e.g. a contact id on an existing contribution. Why is it missing? Maybe the real problem is a typo along the way or some bad logic.
* What is the code actually doing? Is it even needed or is it left over from older code and that is why there is an error? Can it be removed?
* A common variable is `$form.foo` which represents a quickform field, and it will have two subkeys `$form.foo.label` and `$form.foo.html`. Suppose it's the type of field that legitimately may not be present, like a money-related field on a free event. Both `{if $form.foo}` and `{if $form.foo.html}` would give errors in this situation. Note we can't use `{if array_key_exists('html', $form.foo)}` because it will still give the error for as mentioned earlier, but in this case `{if array_key_exists('foo', $form)}` is sufficient if the check was about whether the field exists or not.
* But note there is a big difference for `$form.foo` if it's something like a boolean field, e.g. between `{if array_key_exists('showTitle', $form)}` and `{if $form.showTitle}` when showTitle is 0 or FALSE or NULL. You'll end up with titles showing when they shouldn't. In this case you want to make sure showTitle is always assigned explicitly to something in the php, and then use `{if $form.showTitle}` in the template.
In php
----
(TODO: flesh out this part)
Similar considerations apply on the php end. Using `??` is not always the right choice.
FYI @eileen @bradleythttps://lab.civicrm.org/documentation/docs/dev/-/issues/891Document new queue hook2023-09-23T03:30:46ZeileenDocument new queue hookSee
https://github.com/civicrm/civicrm-core/pull/27526See
https://github.com/civicrm/civicrm-core/pull/27526https://lab.civicrm.org/documentation/docs/dev/-/issues/885Document hook_civicrm_alterApiRoutePermissions2023-04-19T20:08:50ZJonGoldDocument hook_civicrm_alterApiRoutePermissionsWe document `hook_civicrm_alterAPIPermissions` but not `hook_civicrm_alterApiRoutePermissions` which is necessary for APIv4.We document `hook_civicrm_alterAPIPermissions` but not `hook_civicrm_alterApiRoutePermissions` which is necessary for APIv4.https://lab.civicrm.org/documentation/docs/dev/-/issues/882Take the old wiki offline / remove wiki from search results2023-03-25T00:41:00ZJonGoldTake the old wiki offline / remove wiki from search resultsIt pollutes search results and is a poor DX for [developers new to the Civi ecosystem](https://civicrm.stackexchange.com/q/43196/12).
The best solution would be to go page-by-page and take it offline - something I'm willing to help with...It pollutes search results and is a poor DX for [developers new to the Civi ecosystem](https://civicrm.stackexchange.com/q/43196/12).
The best solution would be to go page-by-page and take it offline - something I'm willing to help with in a future (virtual?) sprint - but I'd argue that at this point, it's better completely offline than the current state.https://lab.civicrm.org/documentation/docs/dev/-/issues/883Document new parameters search and display for hook_civicrm_searchKitTasks2023-02-07T22:37:47Zmattwiremjw@mjwconsult.co.ukDocument new parameters search and display for hook_civicrm_searchKitTasksSee https://github.com/civicrm/civicrm-core/pull/25123 and https://github.com/civicrm/civicrm-core/pull/25482See https://github.com/civicrm/civicrm-core/pull/25123 and https://github.com/civicrm/civicrm-core/pull/25482https://lab.civicrm.org/documentation/docs/dev/-/issues/881Add search-kit change log or consolidate change logs2022-10-26T17:31:40ZeileenAdd search-kit change log or consolidate change logsI just put up https://lab.civicrm.org/documentation/docs/dev/-/commit/7ee1cca968d3c89169c7be91236e588f5e5a8fb8 & thought we should probably have a change log for such things. The risk is it isn't maintained well - but I guess that's like...I just put up https://lab.civicrm.org/documentation/docs/dev/-/commit/7ee1cca968d3c89169c7be91236e588f5e5a8fb8 & thought we should probably have a change log for such things. The risk is it isn't maintained well - but I guess that's like all docs...https://lab.civicrm.org/documentation/docs/dev/-/issues/829Keeping up with the APIv4 changelog2022-10-13T23:39:54ZhomotechsualKeeping up with the APIv4 changelog*Created by: colemanw*
APIv4 is still in rapid development and I haven't been keeping the changelog page up-to-date:
https://docs.civicrm.org/dev/en/latest/api/v4/changes/
I'm wondering if it would be possible to leverage the releas...*Created by: colemanw*
APIv4 is still in rapid development and I haven't been keeping the changelog page up-to-date:
https://docs.civicrm.org/dev/en/latest/api/v4/changes/
I'm wondering if it would be possible to leverage the release notes. Each one has a section about api changes. We just need to somehow link that in here.
Any ideas @agh1 ?https://lab.civicrm.org/documentation/docs/dev/-/issues/659Document entities and correct use2022-10-13T22:06:41ZhomotechsualDocument entities and correct use*Created by: aydun*
The background for this is the discussion on https://lab.civicrm.org/dev/membership/issues/13 but applies more generally.
We have good docs for general usage, and for some aspects of development but we don't have ...*Created by: aydun*
The background for this is the discussion on https://lab.civicrm.org/dev/membership/issues/13 but applies more generally.
We have good docs for general usage, and for some aspects of development but we don't have anything that documents how the internal data structures relate and how to use them correctly (kinda ER but for humans!).
For example, if a membership with recurring contributions is created, what entities should result? eg membership, recurring contribution, contribution, etc. When a payment is made on that recurring contribution what should result? - contributions, payment, membership payment, line item, financial transaction, updates to membership ...
The second part of that is how each of those things is created. [The line Eileen pointed out](https://lab.civicrm.org/dev/membership/issues/13#note_21349) shows creating a lineitem will cause a membership payment to be created - unless it already exists, suggesting some ambiguity around whether a membership payment should have already been created. The documentation I have in mind would be something like: To create a membership with recurring contributions: create Entity1 ..., Entity2 ..., Entity3 ... and then Entity4, Entity5, Entity6 will also be created.
Our docs and API tell us for example how to create a Membership Payment, but not the bigger picture of how to correctly record a payment for membership.
A clear picture of these entity relationships and processes would provide a more robust basis for refactoring, enhancements and extensions.
Thoughts?https://lab.civicrm.org/documentation/docs/dev/-/issues/707Document relative date options2022-10-13T15:09:48ZhomotechsualDocument relative date options*Created by: eileenmcnaughton*
CiviCRM ships with a bunch of relative dates- but it's also possible to add option values for more (this is limited based on what was made generic in these 2 prs)
https://github.com/civicrm/civicrm-core...*Created by: eileenmcnaughton*
CiviCRM ships with a bunch of relative dates- but it's also possible to add option values for more (this is limited based on what was made generic in these 2 prs)
https://github.com/civicrm/civicrm-core/pull/14894
and https://github.com/civicrm/civicrm-core/pull/12682https://lab.civicrm.org/documentation/docs/dev/-/issues/832Document when the ok-without-test label should be added to a PR2022-10-13T15:07:40ZhomotechsualDocument when the ok-without-test label should be added to a PR*Created by: eileenmcnaughton*
Just trying to flesh out when a PR would get the 'ok-without-test' label
So far I'm at
1. is very form-layer (wording changes, css, tpl but not postProcess handling)
2. is unreasonably hard to wr...*Created by: eileenmcnaughton*
Just trying to flesh out when a PR would get the 'ok-without-test' label
So far I'm at
1. is very form-layer (wording changes, css, tpl but not postProcess handling)
2. is unreasonably hard to write a test for
3. we are dealing with aa regression under pressure & we need to respect the fact that someone has just 'dropped everything to solve a regression' and not pile more on that situation
https://github.com/civicrm/civicrm-core/pull/17831#issuecomment-658482888
Note that from my point of view I'm trying to review all prs with 'has test' first, followed by 'ok without test' and then 'any others' - which usually require the reviewer to write a testhttps://lab.civicrm.org/documentation/docs/dev/-/issues/844Document hookable menubar colors2022-10-13T15:06:29ZhomotechsualDocument hookable menubar colors*Created by: MegaphoneJon*
https://github.com/civicrm/civicrm-core/pull/14944 discusses the need for documenting the technique for theme developers to make their menubar overrides conditional, but the docs were never written. This tick...*Created by: MegaphoneJon*
https://github.com/civicrm/civicrm-core/pull/14944 discusses the need for documenting the technique for theme developers to make their menubar overrides conditional, but the docs were never written. This ticket will track that documentation.https://lab.civicrm.org/documentation/docs/dev/-/issues/851Not sure where it fits but this documents how to make a payment processor tes...2022-10-13T15:04:56ZhomotechsualNot sure where it fits but this documents how to make a payment processor testable*Created by: eileenmcnaughton*
https://github.com/civicrm/civicrm-core/pull/18350*Created by: eileenmcnaughton*
https://github.com/civicrm/civicrm-core/pull/18350https://lab.civicrm.org/documentation/docs/dev/-/issues/712Document why (if still appropriate) the following is specced2022-10-11T15:18:41ZhomotechsualDocument why (if still appropriate) the following is specced*Created by: eileenmcnaughton*
"IPN payment processors processing a contribution do NOT create civicrm_financial_item, civicrm_financial_trxn, or civicrm_entity_financial_trxn records at the time the transaction is posted to the payment...*Created by: eileenmcnaughton*
"IPN payment processors processing a contribution do NOT create civicrm_financial_item, civicrm_financial_trxn, or civicrm_entity_financial_trxn records at the time the transaction is posted to the payment processor. They are only created at the time of the IPN call back."
https://wiki.civicrm.org/confluence/display/CRM/CiviAccounts+Data+Flow
It's unclear from the document why we would not do the same things for Payment Processor & non payment processor payments. Historically the code treated the 2 very differently but in the real world the distinction has become very grey. If there is a good reason we should document it. Otherwise I suspect we have already started to 'leak' in the direction of treating them the same.
<img width="1306" alt="Screen Shot 2019-10-22 at 5 53 38 PM" src="https://user-images.githubusercontent.com/336308/67259905-e86a7800-f4f4-11e9-8a76-bdc92b9baab8.png">
@JoeMurray @monishdeb @pradpnayak @kcristiano
https://lab.civicrm.org/documentation/docs/dev/-/issues/845Improve extension settings documentation2022-10-11T15:09:26ZMichael McAndrewImprove extension settings documentation@artfulrobot has written a good answer here https://civicrm.stackexchange.com/questions/3458/how-do-i-add-a-new-settings-page-for-my-extension/21597#21597 which is better than the current documentation: https://docs.civicrm.org/dev/en/la...@artfulrobot has written a good answer here https://civicrm.stackexchange.com/questions/3458/how-do-i-add-a-new-settings-page-for-my-extension/21597#21597 which is better than the current documentation: https://docs.civicrm.org/dev/en/latest/framework/setting/#creating-a-new-setting-in-an-extension
https://lab.civicrm.org/documentation/docs/dev/-/issues/864Performance benefits of API chaining2022-10-11T15:05:27ZMichael McAndrewPerformance benefits of API chainingNot sure about the internals of how chaining works in API 4 but wondering if there is a performance benefit to it, or just a syntactical one.
Personally, I have never got into API chaining, and I think that there is a benefit to the cla...Not sure about the internals of how chaining works in API 4 but wondering if there is a performance benefit to it, or just a syntactical one.
Personally, I have never got into API chaining, and I think that there is a benefit to the clarity of doing a get and then and update (for example).
But if there is a performance gain that might change my mind in some instances.
Maybe it is more of an issue when using Ajax and considering round trips to the server?
I'm adding this as the documentation issue, since I think it is worth adding the answer to https://docs.civicrm.org/dev/en/latest/api/v4/chaining/.
But I think it is worth a quick discussion before doing so.
@colemanw - can you help answer this question?colemanwcolemanwhttps://lab.civicrm.org/documentation/docs/dev/-/issues/871Document guzzle as the preferred interface for http requests2022-10-11T14:52:52ZMichael McAndrewDocument guzzle as the preferred interface for http requestsShould we add an http requests section to the reference section?
See https://chat.civicrm.org/civicrm/pl/xgehp38t7ig88gg5soob3wua1yShould we add an http requests section to the reference section?
See https://chat.civicrm.org/civicrm/pl/xgehp38t7ig88gg5soob3wua1y