Field lifecycle and documentation

Kirby 2 Issues 🐛
1

Could somebody please create some documention about fields? Especially how everything ties up with js?

I mean i managed to make some fields looking through sourcecode of other fields but it would make things lot easier if there was something about field lifecycle. Lets say if i want to make js only field, how to return data to be saved? What are all the basefield functions doing… core field classes dont even have comments.

I mean just simple stuff - i just made js only ui i get to wierd issues where my javascript seems to be loaded before the html. Mess with click handlers… How is the js registered (i use assets in the field)? Do i have to register everything as jquery plugin? Do i have to name it in some way? What do i have to return? How gets stuff saved?

My plan is to eventualy use vuejs to make ui because the jquery only approach gets nuts when doing more interactive fields and vue is just much easier/faster (please lets not talk about hype, i hated angular and agree with Bastian decision about Angular panel but i dont see reason why not use smart small lib like vue).

I am confused and while i might figure it out eventualy - i would be really nice if i didn’t have to figure out everything by myself.

I believe Kirby would also have more fields if they are documented correctly :)).

2

We feel your pain. :slight_smile:
Actually we are already planning to improve the Panel to make it easier to extend, but as always we’d rather make it take longer to get it right instead of rushing it, so it may still take some time, no ETA yet.

2 Likes
3

I will try to share my insight on this subject.

JavaScript

Put your scripts into:

  static public $assets = array(
    'js' => array(
      'example.js',
    ),
  );

The panel calls a custom field js by the [data-field] attribute. The attribute given is the jQuery function the panel trys to call.

Add the [data-field] attribute by modifing the content method (example from the sortable field) or if you have a template for your field do it like the structure field.

In general the attribute value should be the same as your field name to prevent any collision with other fields. But don’t choose one where the name is already in use by jQuery.

For a field named example your js could look like something like that:

(function($) {

  var Example = function(element) {
    this.element = $(element);

    this.stuff();
  };

  Example.prototype.stuff = function() {
    // do stuff
  }

  $.fn.example = function() {
    return this.each(function() {
      if ($(this).data('example')) {
        return $(this);
      } else {
        var example = new Example(this);
        $(this).data('example', example);
        return $(this);
      }
    });
  }

})(jQuery);

This way the panel will take care of initializing an reinitializing your script.

Saving

The result() method determines what is saved to the file.
Have a look here.

To retrieve a value take a look at the value() method.

3 Likes
4

Thank you @lukaskleinschmidt actually what helped even more is your sortable field that has comments. I should have thought of looking there sooner (i use it heavily for modules).

I have vue instance itializing and runing fine. Now i just have to figure out bubbling of the events and saving :)).

I WILL GET TO BOTTOM OF THIS!!!

Thanks a bunch.

5

You already have some great answers here. As a complement Kirby Secrets contains undocumented secrets of Kirby. It includes some articles about the panel fields as well. Maybe you can find something useful there.

1 Like