You are here

README.txt in Duration Field 3.0.x

Same filename and directory in other branches
  1. 8.2 README.txt
  2. 8 README.txt
CONTENTS OF THIS FILE
---------------------

 * Introduction
 * Requirements
 * Installation
 * Configuration
 * Form API Element
 * Maintainers


INTRODUCTION
------------

The Duration Field module creates a new Form API form element of type duration,
as well as a Field API field of type duration. A duration is a time period, for
which the granularity can be adjusted to collect any or all of years, months,
days, hours, minutes, and seconds.

This module makes no assumptions as to the type of duration a user would want to
collect, so as such, if they wished, a user could choose to collect years and
seconds only, though generally that wouldn't make sense.

Dates are stored in the system as ISO 8601 Durations.

 * For a full description of the module visit:
   https://www.drupal.org/project/duration_field

 * To submit bug reports and feature suggestions, or to track changes visit:
   https://www.drupal.org/project/issues/duration_field


REQUIREMENTS
------------

This module requires no modules outside of Drupal core.

INSTALLATION
------------

 * Install the Duration Field module as you would normally install a contributed
   Drupal module. Visit https://www.drupal.org/node/1897420 for further
   information.


CONFIGURATION
-------------

To work with the field value programmatically, the field value can be used to
construct a DateInterval object as follows:

<?php
$duration = new \DateInterval($field_value);

// Output years:
$duration->format('%y');

// Output months:
$duration->format('%m');

// Output days:
$duration->format('%d');

// Output hours:
$duration->format('%h');

// Output minutes:
$duration->format('%i');

// Output seconds:
$duration->format('%s');
?>


FORM API ELEMENT
----------------

New form elements can be created within the Form API as follows:

<?php
$element['duration'] = [
  '#type' => 'duration',
  '#title' => t('Duration'),
  '#granularity' => 'y:d:m:h:i:s',
  '#required_elements' => 'y:d:m:h:i:s',
  '#default_value' => 'P1Y2M3DT4H5M6S',
];
?>

* #granularity - A list of elements to show, separated by colons. Included
  elements will be shown in the form element.
    y - years
    m - months
    d - days
    h - hours
    i - minutes
    s - seconds

    Default - y:m:d:h:i:s

* #elements - A list of elements to be required, separated by colons.
  Elements listed will be required within in the form element. Keys are the same
  as for #granularity

* #default_value' - The default value for the element, in Iso8601 duration
  format.


MAINTAINERS
-----------

 * Jay Friendly (Jaypan) - https://www.drupal.org/u/jaypan

File

README.txt
View source
  1. CONTENTS OF THIS FILE
  2. ---------------------
  3. * Introduction
  4. * Requirements
  5. * Installation
  6. * Configuration
  7. * Form API Element
  8. * Maintainers
  9. INTRODUCTION
  10. ------------
  11. The Duration Field module creates a new Form API form element of type duration,
  12. as well as a Field API field of type duration. A duration is a time period, for
  13. which the granularity can be adjusted to collect any or all of years, months,
  14. days, hours, minutes, and seconds.
  15. This module makes no assumptions as to the type of duration a user would want to
  16. collect, so as such, if they wished, a user could choose to collect years and
  17. seconds only, though generally that wouldn't make sense.
  18. Dates are stored in the system as ISO 8601 Durations.
  19. * For a full description of the module visit:
  20. https://www.drupal.org/project/duration_field
  21. * To submit bug reports and feature suggestions, or to track changes visit:
  22. https://www.drupal.org/project/issues/duration_field
  23. REQUIREMENTS
  24. ------------
  25. This module requires no modules outside of Drupal core.
  26. INSTALLATION
  27. ------------
  28. * Install the Duration Field module as you would normally install a contributed
  29. Drupal module. Visit https://www.drupal.org/node/1897420 for further
  30. information.
  31. CONFIGURATION
  32. -------------
  33. To work with the field value programmatically, the field value can be used to
  34. construct a DateInterval object as follows:
  35. $duration = new \DateInterval($field_value);
  36. // Output years:
  37. $duration->format('%y');
  38. // Output months:
  39. $duration->format('%m');
  40. // Output days:
  41. $duration->format('%d');
  42. // Output hours:
  43. $duration->format('%h');
  44. // Output minutes:
  45. $duration->format('%i');
  46. // Output seconds:
  47. $duration->format('%s');
  48. ?>
  49. FORM API ELEMENT
  50. ----------------
  51. New form elements can be created within the Form API as follows:
  52. $element['duration'] = [
  53. '#type' => 'duration',
  54. '#title' => t('Duration'),
  55. '#granularity' => 'y:d:m:h:i:s',
  56. '#required_elements' => 'y:d:m:h:i:s',
  57. '#default_value' => 'P1Y2M3DT4H5M6S',
  58. ];
  59. ?>
  60. * #granularity - A list of elements to show, separated by colons. Included
  61. elements will be shown in the form element.
  62. y - years
  63. m - months
  64. d - days
  65. h - hours
  66. i - minutes
  67. s - seconds
  68. Default - y:m:d:h:i:s
  69. * #elements - A list of elements to be required, separated by colons.
  70. Elements listed will be required within in the form element. Keys are the same
  71. as for #granularity
  72. * #default_value' - The default value for the element, in Iso8601 duration
  73. format.
  74. MAINTAINERS
  75. -----------
  76. * Jay Friendly (Jaypan) - https://www.drupal.org/u/jaypan