Custom Drupal Elements for Forms

Posted on July 9, 2013

One of the most cryptic tasks in Drupal is defining a custom form element. That is, defining your own element types to be used and resused in your forms. This post will walk you through the basics. And there's no better way than to learn by example.

For our example element, let's define one that links to a github or bitbucket repository. These two sites host a lot of open source projects, so it makes sense to have an element that handles both. Note: this guide applies to Drupal 7. You should be able to make it work on Drupal 6 with some minor modifications. Let's call our element gitbucket.

Learning Drupal? Subscribe to my Drupal articles, tips and tutorials.

![3]

Part of what makes the Form API in Drupal so powerful is that we can define compound custom elements. In other words, elements that contain one or more existing elements. This is quite useful for our use case, where we want our gitbucket field to have both, a source field (github or bitbucket) and a username/repository field. So let's get started.

The key to creating a custom element is hook_element_info(), where we provide information about our element. So let's define it.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
<?php

function example_element_info() {
  $elements['gitbucket'] = array(
    '#default_value' => '',
    '#input' => TRUE,
    '#process' => array('example_gitbucket_element_process'),
    '#theme' => array('gitbucket_field'),
    '#theme_wrappers' => array('form_element'),
    '#tree' => TRUE,
    '#value_callback' => 'example_gitbucket_element_value_callback',
  );
  return $elements;
}

As you can see above, we're providing the Form API with quite a bit of info. Let's walk through this hook step by step.

Our #process callback is what gets called when we're going to use the element in a form. This is where we turn our element from a simple definition into the compound element that we want. So we provide a callback function for it. We'll get to that in a bit.

We also define a #theme callback. This is what renders the inside of our element, including the subelements that we'll define. We have a lot of flexibility here when rendering. Using this callback, we'll make sure our element looks nice and readable.

Next we provide #theme_wrappers. As you'd imagine, this wraps all the elements after they come back from the #theme callback. Generally, you can just use the built-in form_element and let it do the work for you. That's exactly what we're doing here.

Last but not least, we define #tree and #value_callback. The first makes sure our nested element structure is preserved for our values, rather than flattened. The second provides a way to process values before they are returned to the form submit function. You need to provide a #value_callback if you want to do fancy processing on the input.

With all of that declared, we can now implement our #process function to construct our very own custom element:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
<?php

function example_gitbucket_element_process($element, $form_state, $complete_form) {

  $element['gitbucket']['source'] = array(
    '#type' => 'select',
    '#empty_option' => '- ' . t('Source') . ' -',
    '#options' => array(
      'github' => 'github://',
      'bitbucket' => 'bitbucket://',
    ),
    '#required' => $element['#required'],
    '#title' => t('Repository Source'),
    '#title_display' => 'invisible',
    '#theme_wrappers' => array(),
  );

  if (isset($element['#default_value']['gitbucket']['source'])) {
    $element['gitbucket']['source']['#default_value'] = $element['#default_value']['gitbucket']['source'];
  }

  $element['gitbucket']['address'] = array(
    '#type' => 'textfield',
    '#size' => 50,
    '#required' => $element['#required'],
    '#title' => t('Repository Name'),
    '#title_display' => 'invisible',
    '#theme_wrappers' => array(),
    '#attributes' => array('placeholder' => 'username/repository'),
  );

  if (isset($element['#default_value']['gitbucket']['address'])) {
    $element['gitbucket']['address']['#default_value'] = $element['#default_value']['gitbucket']['address'];
  }

  return $element;
}

As you can see, we're nesting elements in the snippet above. Our custom element consists of a select field for the repository source, and a textfield for the actual repository. The actual declaration of these fields is straightforward, and you can use almost anything in the Form API.

When nesting elements, there are a couple of quirks to watch out for. First, you probably don't want a bunch of nested titles shown. That's why we set #title_display to invisible. But we still declare a title for error handling purposes. We want the Form API to be able to pinpoint fields required nested fields and the like.

You also don't want the wrapping HTML structure around each individual nested element. You want it outside the entire compound element. So for each nested element, we set #theme_wrappers to an empty array.

And that's it. We load up default values as necessary, and we're done processing our custom elemenet. Let's move on to theming.

We want a nice inline look for our field, so let's keep the theming simple. First we need to register our function, and then implement it. Like so:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
<?php

function example_theme() {
  return array(
    'gitbucket_field' => array(
      'render element' => 'element',
    ),
  );
}

function theme_gitbucket_field($variables) {
  $element = $variables['element'];
  $output = '';
  $output .= drupal_render($element['gitbucket']['source']);
  $output .= " "; // This space forces our fields to have a little room in between.
  $output .= drupal_render($element['gitbucket']['address']);
  return $output;
}

Now we're ready for the last part: the value callback. As you can see, our custom element has two parts. You should select either or none. But what happens if they just select a source with no repository name? If we marked the field as required, Drupal handles that for us by requesting both fields be populated. The problem appears when our field is not marked as required. In this case, if we fill just one and not the other, we want to treat this as the user having left the field empty. We can use the value callback for this 1.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
<?php

function example_gitbucket_element_value_callback($element, $input = FALSE, &$form_state) {
  if ($input !== FALSE) {
    if ($input['gitbucket']['source'] && !$input['gitbucket']['address']) {
      $input['gitbucket']['source'] = '';
    }
    if ($input['gitbucket']['address'] && !$input['gitbucket']['source']) {
      $input['gitbucket']['address'] = '';
    }
    return $input;
  }
  elseif (!empty($element['#default_value'])) {
    return $element['#default_value'];
  }

  return;
}

Value callbacks should be divided into three conditions:

  1. Input is being provided directly. This happens when a form is submitted.
  2. No input is provided, but the field definition has a default value.
  3. No input is provided and there is no default value.

In the first part, we handle the edge case of partial input. If only half the field is filled out, we simply treat it as empty. Then we return the modified input.

And that's it. You're done. You've now defined a custom compound field that can be used in any Drupal forms. For example, let's declare a simple system settings form that uses our newly minted element.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
<?php

function example_form() {
  $form = array();
  $form['required_field'] = array(
    '#type' => 'gitbucket',
    '#title' => t('Your favorite repository'),
    '#required' => TRUE,
    '#default_value' => variable_get('required_field', array()),
  );
  $form['optional_field'] = array(
    '#type' => 'gitbucket',
    '#title' => t('Your least favorite repository'),
    '#default_value' => variable_get('optional_field', array()),
  );
  return system_settings_form($form);
}

Try it out. Fill in partial input and hit submit. You'll see how our fields behave properly even with missing input.


  1. Technically, you can also use validation hooks for this. 

Comments

Martin MaritimMarch 7, 2014, 7:31 a.m.

Very useful, thanks for posting this.

Reply
DacoAug. 4, 2017, 7:42 p.m.

шрифт - глаза сломать можно...

Reply
MasdenzedOct. 24, 2018, 4:11 a.m.

Сейчас займы пользуются большой популярностью. С помощью финансовой помощи реально решить ряд серьёзных вопросов. Временами бывает так, что на самые необходимые вещи не хватает денег. Вы можете хорошо сэкономить время при оформлении займа. Чтобы не стоять в очереди за кредитом в банке, можно оформить займ онлайн.

Временами бывает так, что деньги могут понадобиться очень срочно, и на длительную обработку данных физически нет часа. С помощью online МФО можно получить микрозайм онлайн без отказов , каталог проверенных МФО есть на все-займы-тут.рф, где вы сможете подобрать любой удобный для Вас сервис.

Вы можете получить займ без свидетельств и поручительств. Нет необходимости подготавливать большой список документов, как это надо делать для банка. Также следует отметить, что все ваши документы не будут афишироваться, что сегодня очень важно. Каждая из представленных МФО предоставляет индивидуальные условия. Вы можете оформить заявку на сайте МФО невероятно быстро. Одобрение по заявке вы можете получить в тот же день или через день.

Для получения займ на карту мгновенно круглосуточно без отказа и без проверки подойдёт любая банковская карта. Главное, чтобы она была действительной. На все-займы-тут.рф вы можете оформить моментально займ. Если вас интересует срочный займ, у вас нет недель ждать, пока по вашей заявке примет решение банк, вам лучше обратиться в МФО.

Любой займ вы можете принять в зависимости от того, на каких опциях организация выдаёт займ. Все online заявки рассматриваются в фирмах очень быстро. Как правило, деньги вы сможете вернуть интересующим вас и удобным для вас способом. На портале собран перечень сервисов, в которые можно вернуть деньги даже в праздники или выходные. Все транзакции проходят мгновенно, а использовать можно как Visa, так и MasterCard.

Вне зависимости от того, какая у вас экономическая ситуация, МФО вам предоставят займ. Все компании функционируют круглосуточно, что на самом деле невероятно содействует. Быстрое одобрение также предоставляют некоторые сервисы. Сегодня микрозайм онлайн – это уже не в новизну. Достаточно много лиц пользуются услугами и оформлять кредит с помощью МФО за 20 минут. Это невероятно легко и комфортно.

Стоит также сказать, что с содействием таких МФО вы можете получить займы не только на карту, но и на online кошелек. Если вам необходимо получить деньги на Яндекс.Деньги или на WebMoney, сделать в наши дни это проще простого. Иногда происходит так, что финансовые проблемы не дают спокойно жить. Чтобы не обращаться к знакомым или знакомым, лучше использовать услуги МФО, где взять микрозайм могут даже студенты или люди в возрасте.

Если вам срочно нужны деньги, особенно если кредитная история отсутствует или она плохая, лучше варианта, чем МФО – не придумать. С помощью таких компаний вы можете не только ликвидировать проблемы финансового характера, но и сделать с нуля или повысить свою кредитную историю.

На все-займы-тут.рф вы можете выбрать любую из организаций на подходящих для Вас условий. Получить кредит, виртуально сегодня можно не выходя из дома. Самое интересное, что сумма займа может быть разной. Очень много компаний выдают первоначальный кредит не на большие суммы. Но, после нескольких успешных возвращений вы легко сможете оформить кредит уже на интересующую Вас сумму.

Во многих МФО процентные ставки лояльные. На сайте отображается список самых отменных МФО, где можно моментально оформить займ. Если вам ранее длительно выдавали деньги или плохо консультировали, вам не стоит беспокоиться. На сайте все эти функции объединены сразу же при переходе. Вы сможете забыть про трудности, с которыми вам до этого нужно было сталкиваться раньше. Оформить займ виртуально теперь можно в быстрые сроки и легко!

Reply
MafevikorishNov. 15, 2018, 9:30 p.m.

Временами бывает так, что финансовые активы могут потребоваться безумно быстро. Чтобы не обращаться в банковские учреждения или к друзьям, лучше взять займ виртуально. Вы можете получить финансовые активы сразу же после проверки вашей финансовой истории в других МФО. Все заявления очень моментально обрабатываются менеджерами.

Сейчас оптимально брать займы в проверенных компаниях. Мы предлагаем обращаться на все-займы-тут.рф, где реально получить займ. Если вам нужен микрокредит на лояльных условиях, то выбрать вариант из перечня представленных на портале МФО легко.

займ без процентов на карту мгновенно круглосуточно выдаются парням и женщинам после 18 лет. Если вы хотите получить моментальный займ, это также является преимуществом МФО, так как именно там вы можете получить мгновенные займы на карту без огромных процентов.

Мгновенные займы без отказа и проверок на портале - ВСЕ-ЗАЙМЫ-ТУТ.РФ

На веб-странице доступен каталог проверенных МФО, которые выдают средства под невысокие проценты. Важно выделить и то, что среди МФО размещен список тех, которые выдают срочный займ. Процедура выдачи финансов в этом случае не превышает 25 минут. Вы можете быть спокойны в том, что займ будет выдан моментально. Необходимо также подчеркнуть, что получить средства вы также можете без лишних проверок, как это в данный момент актуально во многих сервисах.

Займ на карту с плохой кредитной историей для всех

Даже если у вас существовали до этого проблемы с МФО, вам не надо переживать. Получить деньги в займ без отказа могут в эти дни даже пенсионеры. Несмотря на то, что суммы выдаются небольшие, получить их реально круглые сутки. Преимуществом сервиса является то, что на нём доступны только те МФО, которые работают круглосуточно. Даже если у вас плохая кредитная история, получить заемные деньги ночью вы также сможете.

Если у вас появились трудности с финансами, а работы официальной нет – не волнуйтесь. Принять деньги в долг могут даже студенты. Вам не надо предоставлять документы с места работы или предоставлять выписки с банковского счета. Компания работает на благо граждан, по этой причине в эти дни безумно много граждан РФ пользуются услугами на все-займы-тут.рф.

На сайте размещены МФО, которые предоставляют средства с учетом разных рисков. Кое-какие сервисы завышают процентные ставки, но срок возврата у них также большой. Если у вас возникнут вопросы насчет получения денег, у каждой МФО есть контактные данные, куда вы можете обратиться по горячей линии.

Reply
OwendoTenNov. 16, 2018, 12:31 a.m.

Покупать зимнюю и демисезонную обувь всегда очень трудно. Этот процесс не только важен сам по себе, но он еще и занимает очень много времени. Если вы стремитесь найти фирменную обувь на зимнее время года, рекомендуем Вам обратить внимание на обувь фирмы UGG.

Сегодня эта обувь популярная в мировом сообществе и безумно много лиц получают удовольствие от того, что они носят сапожки UGG. Качество, уют и крутой вид – это то, над чем работали разработчики. Если вы хотите приобрести качественную обувь, советуем зайти на официальный портал фирмы UGG. На australia-msk.ru вы можете приобрести разные угги. Обилие выбора товаров приятно удивит вас.

Угги Австралия официальный сайт интернет-магазин - australia-msk.ru

Компания UGG популярна во многих странах, в том числе и в Российской Федерации. Вы можете заказать обувь интересующей Вас размерной сетки на официальном сайте где купить угги оригинальные . На данный момент вам больше не потребуется куда-то идти и забирать обувь. Необходимо кликнуть на ресурс интернет-магазина, где вы сможете сделать выбор. У вас есть возможность купить сапожки на февраль или на декабрь. Среди известных моделей в настоящем году пользуются спросом красные женские UGG и мужские желтые UGG.

Необходимо отметить, что компания оказывает услуги по мгновенной доставке товаров. Вы можете находиться в любом регионе РФ. Компания высылает службой доставки обувь. Вы можете связаться с администраторами интернет-магазина и получить полную справку по любым вопросам. Угги компании UGG очень популярны в Российской Федерации. Именно по этой причине вы можете заказать оригинальные UGG для парней, женщин или детей на australia-msk.ru

Сейчас легко подобрать обувь, однако, какая вероятность того, что продукция прослужит вам долго? Чтобы не попасть на китайские подделки, предлагаем использовать удобную и долговечную обувь. Вся обувь компании UGG стильная и прекрасно подойдёт для тех, кто хочет соответствовать всем параметрам моды.

Женские Австралийские UGG приобрести в официальной интернет магазине

Если ваши ножки устали от дискомфортных сапог, рекомендуем рассмотреть универсальные сапожки. Вся обувь изготовляется из натуральных материалов, которые покорили сердца людей. Фирма UGG предлагает крутые варианты, которые соответствуют актуальным тенденциям. Любая девушка или женщина сможет подобрать натуральные сапоги из овчины любого размера. Необходимо выделить и то, что фасон сапог подойдёт как для юных девушек, так и для дам в возрасте.

Вся обувь пошита из овечьего меха и замши. Эти качества обуви согревают ножки и способствуют тому, что бы парень не болел. С содействием обуви UGG можно покорять горные поверхности или суровые сугробы. Эта обувь подойдёт под любые виды брюк. На данный момент обувь фирмы UGG считается неотъемлемой частью гардероба любой современной дамы.

Мужские Австралийские UGG приобрести на официальном сайте

Если Вам необходимы натуральные сапоги или сапожки высокого качества пошива, предлагаем перейти на australia-msk.ru, где невероятно огромный выбор обуви для мужчин и ugg угги официальный сайт . Вы можете приобрести безопасную обувь на любой сезон. Максимальный уют этой обуви способствует тому, чтобы её покупало еще больше парней. Именно из-за этого у компании UGG много поклонников по всему миру. Любой молодой человек сможет выделить свой универсальный стиль с помощью сапожек UGG.

Ботинки этой компании возможно купить и в столице. Забрать обувь возможно по адресу г. Москва, Проспект мира, д. 102, к.1. Если вы желаете в online форме что-то узнать, советуем также писать на info@australia-msk.ru, где консультанты отвечают при первой же возможности.

Детские Австралийский Угги заказать на официальном сайте

Следует также отметить, что лучший подарок для ваших детей зимой – фирменная обувь UGG. Ботинки этой фирмы быстро согреют ножки зимой вашего ребенка. Вы можете быть спокойны, что, одевая ботинки фирмы UGG ваш малыш будет чувствовать себя тепло и безопасно!

Reply
ЕвгенияNov. 13, 2018, 9:44 a.m.

Перезвоните пожалуйста по телефону +7 (495) 248-01-88 Евгения

Reply
LavbikluMNov. 16, 2018, 11:49 a.m.

If you desire to be a agent of the credit network, you should start to get free 30-day membership of one of them. Any of credit networks give for their member’s different conditions. After 30-day membership users must pay for each month. If you desire to get on payday loans in MA, you should go on maybeloan.com where you can receive loans under different conditions.

Today there are a lot of models which provide users with different options of credit. You could take money for interesting for you goals and no one will check the purpose of payment. You can take credit with a various type of credit card. On the link, you could use the monitoring of your data. If you have different questions, you should ask the Experian team. They will suggest interesting conditions for you and will support to solve your financial problems.

More and more men every day receive on money payday loans in AK. If you have never used online credit money, you can use web services. With their support, you can make blare commercials, make your own business, do any purchases and use money 24/7. Every average family one per life uses short-term payday loans in AK. In different cases gus get on money for education for their children. As rule, families in the USA lay off saving for education process for their children from the moment of birth.

If you wish to have point payday loans in Alaska by the online sources, it is possible to do. Every year, more and more people use web banking services. You can take Maryland bad credit installment loans here. With the borrowed money, you could also treat children or use cash in your own goals. You must know that money which will grant for you stand out from individual accumulation. That is why persons who don’t return cash punished.

You can use quick payday loans in Florida. In this town, there are many companies which are grant coins. But in Florida, there are many dishonest people. That is why credit organizations don’t provide money, everybody. They check your private information. If you have any issues with banking systems in the USA, they may don’t furnish for your cash. But at MayBeloan organization you can take money even you have bad credit payday loans in Idaho.

However, if you have some problems with banks in Kansas, you must use web service and take payday loans in Kansas. In Kansas, there are a lot of banking houses and any of them have special requirements for the borrowers. If you haven’t the possibility to receive dollars in Kansas, you must go on https://maybeloan.com/payday-loans/nj/nj-newark.html . Currently this firm is very famous on the web. Not only citizenships from the US utilize services of this office. There are also a lot of guys from border areas near Mexico who also can utilize this service. If you desire to get a cash advance in Kentucky, you could also utilize it. Women from Kentucky in different ways don’t calculate their expenses. That is the reason why in different ways they should use loans.

Last years more and more people prefer to do online purchases. If you desire to get payday loans in Maryland, you should use web service. Conditions which are working there will help everybody. If you prefer to get cash for your credit card or virtual wallet, it is probable to do. Necessary to the item before will be done this manipulation.

Also, you must know that at maybeloan.com there are a lot of members. They utilize various kinds of borrowed money. When you will have different questions, you should ask a team of specialists. At website is working technical support. They will suggest you with various problems.

At the website you also can find various options. They may interest you. You can utilize Visa or MasterCard when you will obtain money. These cards are main credit cards. That is why more and more people in the United States utilizing them.

Reply
ЕвгенияNov. 6, 2018, 6:37 p.m.

Перезвоните пожалуйста по телефону +7 (495) 248-01-88 Евгения

Reply
ВикторNov. 8, 2018, 2:37 p.m.

Перезвоните мне пожалуйста 8(495) 248-01-88 Виктор

Reply
ВикторNov. 12, 2018, 3:51 p.m.

Перезвоните мне пожалуйста 8(495) 248-01-88 Виктор

Reply
ЕвгенияNov. 16, 2018, 9:44 a.m.

Перезвоните пожалуйста по телефону 8 (499) 490-26-28 Евгения

Reply

Post New Comment