# Usage¶

Add `djfractions`

to `settings.INSTALLED_APPS`

## Model Fields¶

## DecimalFractionField¶

```
djfractions.models.DecimalFractionField(verbose_name=None,
name=None,
max_digits=None,
decimal_places=None,
limit_denominator=None,
coerce_thirds=True,
**kwargs)
```

Takes a `fractions.Fraction`

value, stores it as a decimal value,
and then returns it as a `fractions.Fraction`

. This field is highly
based on Django’s `models.DecimalField`

implementation and so
the max_digits and decimal_places arguments are required.

param str verbose_name: | |
---|---|

The verbose name of the field | |

param str name: | Name of the field |

param int max_digits: | |

Maximum number of digits to use for the Decimal representation | |

param int decimal_places: | |

Maximum number of decimal places to use for the Decimal representation | |

param int limit_denominator: | |

Limits the fraction’s denominator to this value if it is set. | |

paraam bool coerce_thirds: | |

If True, then when values which appear to be Decimal values which started as 1/3 or 2/3 will be forced back to 1/3 or 2/3 when retrieved from the database. |

## Form Fields¶

### FractionField¶

```
FractionField(max_value=None,
min_value=None,
coerce_thirds=True,
limit_denominator=None,
use_mixed_numbers=True)
```

Returns a `fractions.Fraction`

instance. Takes a string formatted
as a fraction such as 1/4, 1 1/4, 1-1/4, 1 and 1/4, or -1/4 as input in a form.

param Decimal max_value: | |
---|---|

The maximum value allowed for this field | |

param Decimal min_value: | |

The minimum value allowed for this field | |

param int limit_denominator: | |

Limits the fraction’s denominator to this value if it is set. | |

param bool coerce_thirds: | |

If True, then when values which appear to be Decimal values which started as 1/3 or 2/3 will be forced back to 1/3 or 2/3 when retrieved from the database. | |

param bool use_mixed_numbers: | |

If True initial values which are decimals and floats greater than 1 will be converted to a mixed number such as 1 1/2 in the form field’s value. If False then improper fractions such as 3/2 will be created. Defaults to True. |

Example:

```
from django import forms
from djfractions.forms import FractionField
class MyForm(forms.Form):
a_fraction = FractionField()
```

### DecimalFractionField¶

```
DecimalFractionField(max_value=None,
min_value=None,
coerce_thirds=True,
limit_denominator=None,
use_mixed_numbers=True,
max_digits=None,
decimal_places=None)
```

Returns a `decimal.Decimal`

instance. Takes a string formatted
as a fraction such as 1/4, 1 1/4, 1-1/4, 1 and 1/4, or -1/4 as input in a form.

param bool coerce_thirds: | |
---|---|

Defaults to True. If True then .3 repeating is forced to 1/3 rather than 3/10, 33/100, etc. and .66 and .67 are forced to 2/3. | |

param int limit_denominator: | |

Set a maximum denominator to be used on fractions created from the field input. | |

param bool use_mixed_numbers: | |

If True initial values which are decimals and floats greater than 1 will be converted to a mixed number such as 1 1/2 in the form field’s value. If False then improper fractions such as 3/2 will be created. Defaults to True. | |

param max_value: | |

The maximum value allowed | |

param min_value: | |

The minimum value allowed | |

param int decimal_places: | |

The maximum number of decimal places the resulting Decimal value may have | |

param int max_digits: | |

The maximum number of digits, including decimal places, the resulting Decimal may have. |

Example:

```
from django import forms
from djfractions.forms import DecimalFractionField
class MyForm(forms.Form):
a_fraction = DecimalFractionField()
```

## Template Tags¶

### display_fraction¶

`{% display_fraction value limit_denominator allow_mixed_numbers coerce_thirds %}`

The display_fraction tag displays a formatted fraction in an HTML template. It takes a value and optional parameters to limit the denominator, allow mixed numbers, and adjust decimal/float values which usually are the result of rounding thirds back to thirds based fractions.

The output of this tag can be changed by overriding the `djfractions/display_fraction.html`

template. This is because there are a number of style choices you might make depending
on needs. In some cases <sup> and <sub> tags may cause issues with screen readers. You
may just want to add css classes for easier styling. The template context also includes
a `unicode_entity`

value which has the html entity for the unicode value of a fraction
if one is available. The unicode html entity is preferred by some people, but only a
small number of fractions are supported (particularly if you must support very old browsers)
and the styling is frequently difficult to match up exactly with <sup> and <sub> tags.:

```
{% load fractions %}
{% display_fraction 1.5 %}
```

Would output:

```
1 <sup>1</sup>⁄<sub>2</sub>
```

The template context:

- whole_number
- The whole number part of a fraction. If
`allow_mixed_numbers`

is False then this will always be 0. - numerator
- The numerator of a fraction. For values which are only a whole number the numerator will be 0.
- denominator
- The denominator of a fraction. For values which are only a whole number the denominator will be 1 for a fraction of 0/1.
- unicode_entity
- The unicode_entity is the html entity for the unicode fraction if one exists.
- allow_mixed_numbers
- The value passed to the tag for
`allow_mixed_numbers`

. Knowing this can be useful in template display logic.

The following unicode fraction HTML entities are supported by django-fractions. They may not all be supported by your browser.

Entity | IE 11 | Firefox 39 | Chrome 44 |
---|---|---|---|

½ | Yes | Yes | Yes |

⅓ | Yes | Yes | Yes |

⅔ | Yes | Yes | Yes |

¼ | Yes | Yes | Yes |

¾ | Yes | Yes | Yes |

⅕ | Yes | Yes | Yes |

⅖ | Yes | Yes | Yes |

⅗ | Yes | Yes | Yes |

⅘ | Yes | Yes | Yes |

⅙ | Yes | Yes | Yes |

⅚ | Yes | Yes | Yes |

&frac17; | No | No | Yes |

⅛ | Yes | Yes | Yes |

⅜ | Yes | Yes | Yes |

⅝ | Yes | Yes | Yes |

⅞ | Yes | Yes | Yes |

### display_improper_fraction¶

`{% display_improper_fraction value limit_denominator coerce_thirds %}`

The display_improper_fraction tag works the same as display_fraction with its allow_mixed_numbers set to False. It is just a shortcut for a common use case.:

```
{% load fractions %}
{% display_improper_fraction 1.5 %}
```

Would output:

```
<sup>3</sup>⁄<sub>2</sub>
```