E() throws a warning if condition is undefined

The CMS Questions
1

:face_vomiting: [oops, excuse me]

e() throws a warning if condition is undefined. One might assume that’s what it is made for.
More fun? Try to find some docs about thumb() vs. resize().

2

Please have a look at the documentation for the e() helper if you haven’t yet. I updated it recently with some background information about what is possible or not with this method.

If that doesn’t help you, it definitely helps if you always provide the code that doesn’t work, because my eyes are not penetrating enough to stare at your computer from here.

3

Well, I’m not wanting to be impolite, I’m just trying to express my continuing frustration about every next step not being as (I) expected. In general – after three month on a quick shot project update.

In this case, the said warning occurs on passing an undefined variable to the function, not within the function. Admittedly, there’s nothing to do about this, and nothing wrong actually. Warnings may be useful, my fault.

But in the end, this helper function appears to be rather misleading than helpful. It’s the good old empty() that one will want to use.

	function e($condition, $value, $alternative = null)
	{
		echo $condition ? $value : $alternative;
	}

Please save your penetrating powers for other parts of the docs, they do require some love. :broken_heart:

4

The problem is that airing frustration doesn’t help to improve the docs, we need to understand clearly, where this frustration comes from or rather what exactly you are missing.

For example, $file->thumb() and $file->resize() are quite extensively documented with examples. There is also a complete guide about resizing images. So what exactly is missing?

I’m very willing to update and improve the docs, but I need to understand it.

5

This is the way:

<?php e(!empty($condition), '👍', '👎') ?>

<?= empty($condition) ? '👎' : '👍') ?>
6

As for the docs:

Search for thumb leads to (best guess of dozens):

  • Lacks hint to use ->url() to make it work.
  • Parameters array further down on the page looks like configuration options on first sight.
  • What is the string for the JPEG format, jpg or jpeg?
  • What does $image->thumb(...)->html(); do, escape or render tag?
  • Tiny link to the Guide:
    Resizing & cropping images | Kirby CMS
  • No thumb() function example, just resize()
    Search for resize leads to (guess again):
    $file->resize() | Kirby CMS
  • Figure out yourself whether to call ->url() or not, or which of both functions to use.

General problems:

  • Docs split up into Guide, Reference and Cookbook.
  • Search finds too many technical results that bear hardly any information. And you never know which result is the relevant one.
  • Too many overlapping classes and helpers and tools and backend and panel topics. Dude, where is my answer?
  • So close and yet so distant: page and file (or should I write $page and $file or Page:: and File::?). Both should have the same interface wherever possible.
  • Missing features, for example: Why does default in file blueprints not accept any queries while other fields do?
  • Varying array structures for srcset(), confusingly mixed with varying code styles in the docs:
[300, 800, 1024]
[800  => '1x']
['1x' => ['width' => 38]]
['400w'  => ['width' => 400]],
  • srcset() generated files do not have the expected intrinsic sizes if the source file is smaller, that crashes the layout and makes that sugar function useless.
  • Calling thumb() in a loop instead seems to unexpectedly bypass caching, useless attempt.
  • And those are just current examples.

General recommendations:

  • Please unify the docs sections to a single page each, start with an introduction and continue to the advanced topics right there.
  • Explain your conventions somewhere: $page vs. Page:: vs. page().
  • Please keep it simple and consistent, rid the redundancies in code and docs.
  • Get the goodies to work anywhere, avoid all the disappointments.
  • Please stop messing with common PHP syntax like e() above or even worse: $field->isEmpty() and $collection->empty()!
  • Beware of Betriebsblindheit.
8

Thank you for adding those details. Quite a few things you mention above are not related to the docs, though, it’s important that we keep these things separate, otherwise they are not actionable.

  • For example, your problem regarding the e() helper has nothing to do with the documentation, you would run into the same issue with every single PHP function or method if you add an undefined variable as parameter.

    PHP’s isset() and empty() are not functions, but language constructs.

Having said that, you have some very valid points, and I myself keep fighting the search :wink:

Just as a tip, it helps when searching for "page something2 etc. to narrow down the results.

9

One more exempli gratia (again related to general frustration by both cluttered docs and unexpected failure):

<a href="<?= $image->content()->link() ?>">

The topic is hard to look up in the search (escape, reserved). Search for ‘content()’ result no. 18 is not informative ($file->content() | Kirby CMS). And worst of all: it does not even work. I am going to rename the field.