Custom form: How to implement a module's field widget

Question

In my custom form I have a file upload, which follows the array structure of file_element_info() in file.module in core. This is consistent with examples in examples module and date module has _date_api_element_info().

But looking at geofield or at openlayers and other modules I can not see what array values are possible/required.

As a general rule how do I find out how to add a field of a specific type to a custom form?

---

Edit #1: Just read Where can I find complete documentation of hook_field_info? and everyone is being really helpful about Field API, but it is a steep learning curve. A specific example would really help (an not one of the simple core field types).

---

Edit #2: So on my particular example in geofield.module I got (got the same using dpm(field_info_field_types('geofield'));):

function geofield_field_info() {
  return array(
    'geofield' => array(
      'label' => 'Geofield',
      'description' => t('This field stores geo information.'),
      'default_widget' => 'geofield_wkt',
      'default_formatter' => 'geofield_wkt',
      'instance_settings' => array(
        'local_solr' => array(
          'enabled' => FALSE,
          'lat_field' => 'lat',
          'lng_field' => 'lng',
        ),
      ),
      'property_type' => 'geofield',
      'property_callbacks' => array('geofield_property_info_callback'),
    ),
  );
}

But how does that translate to a form field array?

$form['location'] = array(
    '#title' => t('Location'),
    '#type' => 'geofield',
    '#required' => TRUE,
);

Or do I have the wrong end of the stick here?

Answer 1

In addition to the info posted by @Clive I think it's important to note that this problem can be addressed the other way round[*]: create a node type (or other entity type) with the required fields, and capture the data to process it as you wish when the content is saved.

To do this you would:

1. Create a custom content type (or other entity type) with the fields you need ;
2. Implement hook_form_alter to modify your form if you need special features that are not provided by normal content type forms.

From there it depends what you want to do. If you want the content saved (so that it is stored), and want to process the data after it has been saved, then you could implement hook_entity_insert. If you also want to process the data before it is saved, you could add your own submit handler in hook_form_alter as such:

array_unshift($form['actions']['submit']['#submit'], 'my_submit_handler');

If you want the data after it is submitted, but don't want it saved, you could replace the submit handler with your own:

$form['actions']['submit']['#submit'] = array('my_submit_handler');

[*] I realise I'm not answering the question, but I'm offering a solution to the problem :)

Answer 2

Further to Alice's answer, you could also create your own Entity type and add fields to its instances. This may seem pretty daunting but the Model Entities module does a pretty good job of providing sample implementations of all the entity hooks.