ElggForm API

ElggForm.php

<?php

class ElggForm {
  // $name should correspond to the Elgg action, e.g. ‘blogs/add’
  function __construct($name, $params);

  function registerInput($name, $options); // adds an input; should return form or input?
  function getInput($name); // returns the input
  function removeInput($name); // returns the removed input

  // Helper function for core. Triggers hooks so plugins can customize
  function init();

  // Returns list of problems to display to the user. Automatically called by action system.
  function getErrors();
}

hook.php

<?php

elgg_register_plugin_hook_handler('init:form', 'blog:add', 'blog_form_blog_add');

function blog_form_blog_add(..., ElggForm $form) {
  
  $form->registerInput('title', array(
    'type' => 'text',
    'required' => true,
    'maxlength' => 128
  ));

  $form->registerInput('icon', array(
    'type' => 'file',
    'accept' => 'image/*'
  ));

  $form->registerInput('tags', 'tags');

  if (elgg_is_active_plugin('categories')) {
    $form->registerInput('category', 'text');
  }
  
  $form->registerInput('comments_on', array(
    'type' => 'select', // or 'checkboxes' or 'radios'
    'options' => array('yes' => elgg_echo('yes'), 'no' => elgg_echo('no')),
    'required' => true,
  ));

}

output.html

<!-- If an ID is not provided, a unique one is assigned to the form. These are not consistent across pages. -->
<!-- Enctype is automatically added because one of the input types is "file" -->
<form action="/action/blog/add" method="POST" id="elgg-form-1234" class="elgg-form elgg-form-blog-add" enctype="multipart/form-data">
  <fieldset>
    <!-- A wrapper div is added with a class indicating required so that we can use CSS to style labels of required inputs -->
    <div class="elgg-input-wrapper elgg-state-required">
      <!-- labels are automatically assigned the ID of the associated element -->
      <label for="elgg-form-1234-title" class="elgg-input-label">Title</label>

      <!-- If not provided, ID’s of inputs are generated from the ID of the form + name of input -->
      <!-- HTML5 form validation attributes are added appropriately for client-side validation -->
      <input type="text" name="title" id="elgg-form-1234-title" required maxlength="128" />
    </div>
    
    <div class="elgg-input-wrapper">
      <label for="elgg-form-1234-icon" class="elgg-input-label">Icon</label>
      <input type="file" name="icon" id="elgg-form-1234-icon" accept="image/*" />
    </div>

    <fieldset class="elgg-input-wrapper elgg-state-required">
      <!-- input/checkboxes uses a fieldset to wrap the inputs. -->
      <!-- Can’t use <label> here because there is more than 1 <input> element -->
      <legend class="elgg-input-label">Checkbox Options</legend>
      <ul class="elgg-input-checkboxes">
        <li><label><input type="checkbox" name="options[]" value="1" /> Checkbox 1</label></li>
        <li><label><input type="checkbox" name="options[]" value="2" /> Checkbox 2</label></li>
      </ul>
    </fieldset>

    <!-- Form automatically inserts anti-CSRF tokens, as usual since 1.7 -->
    <input type="hidden" name="__elgg_token" value="2invnf4deij3939de" />
    <input type="hidden" name="__elgg_ts" value="1234567890" />
  </fieldset>
</form>