# codi-cooperatiu-internal-tools
Internal tools and modules of Codi Cooperatiu
## flowbite_css
`flowbite_css` automatically applies form customizations. These customizations use Flowbite styles, a customization of Tailwind.
### Configuration
To use these customizations, you need to add the `flowbite_css` app to the `INSTALLED_APPS` parameter in the `settings.py` file.
#### CODI_COOP_ENABLE_MONKEY_PATCH
The `CODI_COOP_ENABLE_MONKEY_PATCH` parameter in the `settings.py` file controls whether a monkey patch is applied to Django's form fields within your application.
By default, the `CODI_COOP_ENABLE_MONKEY_PATCH` parameter is disabled (`False`). This means the monkey patch will not be applied. If you want to enable the monkey patch, you need to add the `CODI_COOP_ENABLE_MONKEY_PATCH` parameter to the `settings.py` file and set it to `True`.
#### Examples:
**Enable monkey patching:**
```python
# settings.py
CODI_COOP_ENABLE_MONKEY_PATCH = True
```
When this parameter is enabled (`True`), Django form fields such as `CharField`, `EmailField`, `IntegerField`, `ChoiceField`, `MultipleChoiceField`, and `BooleanField` will use the custom fields defined in your application (`CharBoundField`, `BooleanBoundField`, etc.), enabling custom styling and behavior in your forms.
**Disable monkey patching:**
```python
# settings.py
CODI_COOP_ENABLE_MONKEY_PATCH = False # Default value
```
If this parameter is disabled (`False`), Django's form fields will work with their default behavior and styling, without additional customizations.
#### FORM_RENDERER
You can also use a custom template to render all the HTML associated with the fields (`<label />` and any other HTML) with Flowbite classes. In this case, you need to use the `CustomFormRenderer` form renderer by configuring the `FORM_RENDERER` parameter in the `settings.py` file:
```python
# settings.py
FORM_RENDERER = "flowbite_css.renderers.CustomFormRenderer"
```
### Available fields
This library monkey patches many of the default Django fields, meaning that
when you use these Django fields as you would normally do in any model,
you will actually end up using a version of the field that uses a custom
template.
The custom template is specified at `renderers.CustomFormRenderer`.
The custom field templates define the field part of the form control, which means,
the part that is not the widget itself.
As you'll see in every template in the `fields` directory, there's the markup for
rendering labels, errors and so on, but the control itself is rendered with:
`{{ field }}`
This is the part depends on what widget is specified in the Django Form class
for that field.
We needed to control the classes that will be included in the control itself
(the widget), which needed to be different depending on having or not an error
in the field.
The problem is that when Django renders the widget, the context does not include
any way to know if the field had an error or not.
Check `forms.BaseBoundField` to understand how we solved the problem.
#### CharField, EmailField, IntegerField, ChoiceField, MultipleChoiceField
Bound field that sets the custom classes in the widget: `forms.CharField`
Custom field template: `fields/other.html`.
#### BooleanBoundField
Bound field that sets the custom classes in the widget: `forms.BooleanBoundField`
Custom field template: `fields/checkbox.html`.
#### FileBoundField
Bound field that sets the custom classes in the widget: `forms.FileBoundField`
Custom field template: `fields/file.html`.
#### TimeBoundField
Bound field that sets the custom classes in the widget: `forms.TimeBoundField`
Custom field template: `fields/time.html`.
To use this field is necessary to use the `widgets.FlowBiteTimeInput`
widget in your form's field.
#### DateBoundField
Bound field that sets the custom classes in the widget: `forms.DateBoundField`
Custom field template: `fields/date.html`.
To use this field is necessary to use the `widgets.FlowBiteDateInput`
widget in your form's field.
### Available widgets
The widgets in this section can work with the `CharField` field classes and
template, which is monkey patched to use the `CharBoundField` as a bound field, and
therefore, the field part will be rendered with the `fields/other.html` tempalte.
In other words, the only part that we need to override to achieve the desired
result is the widget template and/or properties.
#### Standard numeric input
In most cases we want to show a numeric field that doesn't come with the up and
down arrows to increase and decrease the number.
Additionally, we want to control how the number is rendered in the field, i.e.,
if we're outputting the number with commas as a decimal separator, some browsers
will modify the numeric input controls and replace the decimal separator with
dots, causing inconsistent behavior.
To achieve that we need the input control to be a `text` type, and to add to it
a `data-input-counter` property that will limit the field to numeric characters.
Implementation: use the widget `widgets.FlowBiteNumericInput` as you would
normally do with any Django widget.
#### Incremental numeric input
This input displays a plus and minus buttons at the sides of the control for
increasing and decrementing the number.
Implementation: use the widget `widgets.FlowBiteNumericIncrementalInput` as you would
normally do with any Django widget.
# Contribution
## Install Requirements
Make sure you are using python >3.10.
Install the development dependencies by navigating to the "codi-cooperatiu-internal-tools" folder and running:
```commandline
pip install -r requirements.txt
```
In addition to these requirements, you also need to install Django. To install the current version of Django:
```commandline
pip install django
```
The code comes with git hook scripts. These can be installed by running:
```commandline
pre-commit install
```
The pre-commit hook will now run automatically when making a git commit, checking adherence to the style guide (black, isort, and flake8).
## Run Tests
Before submitting a pull request, run the full test suite of "codi-cooperatiu-internal-tools" using:
```commandline
make test
```
If you do not have `make` installed, the test suite can also be executed using:
```commandline
pytest --ds=tests.test_settings --cov=flowbite_classes
```
## Run linting, formatting and tests using tox
[Install tox](https://tox.wiki/en/4.23.2/installation.html) in a isolated
environment, for exampel if you use pip, run:
```commandline
python -m pip install --user tox
```
Then you can run it with:
```commandline
python -m tox
```
One of the tox commands is the linter, you can run it alone with:
```commandline
python -m tox -e lint
```
Note that tox is meant to be run in the github action that will provide different
python versions, but if you run it like that it will only run in the version
that you have in your environment.
## Publishing a New Version to PyPI
To release a new version of the library to PyPI, follow these steps:
1. **Prepare a Release Branch:**
- Ensure all changes are merged into the `master` branch.
- Create a new branch named after the release version (e.g., `v1.2.3`).
- Update the `version` field in the `project` section of the `pyproject.toml` file to the new release version.
- Commit the changes with a message like `Version <release-version>`.
- Push the branch to the remote repository and create a pull request titled `Version <release-version>`.
2. **Tag the Release:**
- Once the pull request has been reviewed and merged, create a Git tag for the release. Use the following command:
```bash
git tag -a <release-version> <commit> -m "Release <release-version>"
```
Replace `<release-version>` with the version number (e.g., `v1.2.3`) and `<commit>` with the commit hash of the merged pull request.
- Push the tag to the remote repository:
```bash
git push origin <release-version>
```
3. **Create a GitHub Release:**
- Open the [GitHub Releases page](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release).
- Click "Draft a new release."
- In the **Tag version** field, select the previously pushed tag `<release-version>`.
- Use `<release-version>` as the release title.
- In the description, list the changes introduced in this release compared to the previous version.
- Click "Publish release."
4. **Automatic Deployment:**
- Once the release is published, GitHub Actions will automatically trigger the deployment process and publish the new version of the library to PyPI, as configured in the repository.
Raw data
{
"_id": null,
"home_page": null,
"name": "codi-cooperatiu-internal-tools",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "django, forms, flowbite",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/64/88/6cfe5a0c8b06724dac77ceb04289ec5f8402d1e658b78dbd2428836f908b/codi_cooperatiu_internal_tools-0.2.1.tar.gz",
"platform": null,
"description": "# codi-cooperatiu-internal-tools\n\nInternal tools and modules of Codi Cooperatiu\n\n## flowbite_css\n\n`flowbite_css` automatically applies form customizations. These customizations use Flowbite styles, a customization of Tailwind.\n\n### Configuration\n\nTo use these customizations, you need to add the `flowbite_css` app to the `INSTALLED_APPS` parameter in the `settings.py` file.\n\n#### CODI_COOP_ENABLE_MONKEY_PATCH\n\nThe `CODI_COOP_ENABLE_MONKEY_PATCH` parameter in the `settings.py` file controls whether a monkey patch is applied to Django's form fields within your application.\n\nBy default, the `CODI_COOP_ENABLE_MONKEY_PATCH` parameter is disabled (`False`). This means the monkey patch will not be applied. If you want to enable the monkey patch, you need to add the `CODI_COOP_ENABLE_MONKEY_PATCH` parameter to the `settings.py` file and set it to `True`.\n\n#### Examples:\n\n**Enable monkey patching:**\n\n```python\n# settings.py\n\nCODI_COOP_ENABLE_MONKEY_PATCH = True\n```\n\nWhen this parameter is enabled (`True`), Django form fields such as `CharField`, `EmailField`, `IntegerField`, `ChoiceField`, `MultipleChoiceField`, and `BooleanField` will use the custom fields defined in your application (`CharBoundField`, `BooleanBoundField`, etc.), enabling custom styling and behavior in your forms.\n\n**Disable monkey patching:**\n\n```python\n# settings.py\n\nCODI_COOP_ENABLE_MONKEY_PATCH = False # Default value\n```\n\nIf this parameter is disabled (`False`), Django's form fields will work with their default behavior and styling, without additional customizations.\n\n#### FORM_RENDERER\n\nYou can also use a custom template to render all the HTML associated with the fields (`<label />` and any other HTML) with Flowbite classes. In this case, you need to use the `CustomFormRenderer` form renderer by configuring the `FORM_RENDERER` parameter in the `settings.py` file:\n\n```python\n# settings.py\n\nFORM_RENDERER = \"flowbite_css.renderers.CustomFormRenderer\"\n```\n\n### Available fields\n\nThis library monkey patches many of the default Django fields, meaning that\nwhen you use these Django fields as you would normally do in any model,\nyou will actually end up using a version of the field that uses a custom\ntemplate.\n\nThe custom template is specified at `renderers.CustomFormRenderer`.\n\nThe custom field templates define the field part of the form control, which means,\nthe part that is not the widget itself.\nAs you'll see in every template in the `fields` directory, there's the markup for\nrendering labels, errors and so on, but the control itself is rendered with:\n\n`{{ field }}`\n\nThis is the part depends on what widget is specified in the Django Form class \nfor that field.\n\nWe needed to control the classes that will be included in the control itself\n(the widget), which needed to be different depending on having or not an error\nin the field.\n\nThe problem is that when Django renders the widget, the context does not include\nany way to know if the field had an error or not.\n\nCheck `forms.BaseBoundField` to understand how we solved the problem.\n\n#### CharField, EmailField, IntegerField, ChoiceField, MultipleChoiceField\n\nBound field that sets the custom classes in the widget: `forms.CharField`\nCustom field template: `fields/other.html`.\n\n#### BooleanBoundField\n\nBound field that sets the custom classes in the widget: `forms.BooleanBoundField`\nCustom field template: `fields/checkbox.html`.\n\n#### FileBoundField\n\nBound field that sets the custom classes in the widget: `forms.FileBoundField`\nCustom field template: `fields/file.html`.\n\n#### TimeBoundField\n\nBound field that sets the custom classes in the widget: `forms.TimeBoundField`\nCustom field template: `fields/time.html`.\n\nTo use this field is necessary to use the `widgets.FlowBiteTimeInput`\nwidget in your form's field.\n\n#### DateBoundField\n\nBound field that sets the custom classes in the widget: `forms.DateBoundField`\nCustom field template: `fields/date.html`.\n\nTo use this field is necessary to use the `widgets.FlowBiteDateInput`\nwidget in your form's field.\n\n### Available widgets\n\nThe widgets in this section can work with the `CharField` field classes and\ntemplate, which is monkey patched to use the `CharBoundField` as a bound field, and \ntherefore, the field part will be rendered with the `fields/other.html` tempalte.\n\nIn other words, the only part that we need to override to achieve the desired\nresult is the widget template and/or properties.\n\n#### Standard numeric input\n\nIn most cases we want to show a numeric field that doesn't come with the up and\ndown arrows to increase and decrease the number.\nAdditionally, we want to control how the number is rendered in the field, i.e.,\nif we're outputting the number with commas as a decimal separator, some browsers\nwill modify the numeric input controls and replace the decimal separator with\ndots, causing inconsistent behavior.\n\nTo achieve that we need the input control to be a `text` type, and to add to it\na `data-input-counter` property that will limit the field to numeric characters.\n\nImplementation: use the widget `widgets.FlowBiteNumericInput` as you would\nnormally do with any Django widget.\n\n#### Incremental numeric input\n\nThis input displays a plus and minus buttons at the sides of the control for\nincreasing and decrementing the number.\n\nImplementation: use the widget `widgets.FlowBiteNumericIncrementalInput` as you would\nnormally do with any Django widget.\n\n# Contribution\n\n## Install Requirements\n\nMake sure you are using python >3.10.\n\nInstall the development dependencies by navigating to the \"codi-cooperatiu-internal-tools\" folder and running:\n\n```commandline\npip install -r requirements.txt\n```\n\nIn addition to these requirements, you also need to install Django. To install the current version of Django:\n\n```commandline\npip install django\n```\n\nThe code comes with git hook scripts. These can be installed by running:\n\n```commandline\npre-commit install\n```\n\nThe pre-commit hook will now run automatically when making a git commit, checking adherence to the style guide (black, isort, and flake8).\n\n## Run Tests\n\nBefore submitting a pull request, run the full test suite of \"codi-cooperatiu-internal-tools\" using:\n\n```commandline\nmake test\n```\n\nIf you do not have `make` installed, the test suite can also be executed using:\n\n```commandline\npytest --ds=tests.test_settings --cov=flowbite_classes\n```\n\n## Run linting, formatting and tests using tox\n\n[Install tox](https://tox.wiki/en/4.23.2/installation.html) in a isolated\nenvironment, for exampel if you use pip, run:\n\n```commandline\npython -m pip install --user tox\n```\n\nThen you can run it with:\n\n```commandline\npython -m tox\n```\n\nOne of the tox commands is the linter, you can run it alone with:\n\n```commandline\npython -m tox -e lint\n```\n\nNote that tox is meant to be run in the github action that will provide different\npython versions, but if you run it like that it will only run in the version\nthat you have in your environment.\n\n## Publishing a New Version to PyPI\n\nTo release a new version of the library to PyPI, follow these steps:\n\n1. **Prepare a Release Branch:**\n - Ensure all changes are merged into the `master` branch.\n - Create a new branch named after the release version (e.g., `v1.2.3`).\n - Update the `version` field in the `project` section of the `pyproject.toml` file to the new release version.\n - Commit the changes with a message like `Version <release-version>`.\n - Push the branch to the remote repository and create a pull request titled `Version <release-version>`.\n\n2. **Tag the Release:**\n - Once the pull request has been reviewed and merged, create a Git tag for the release. Use the following command:\n ```bash\n git tag -a <release-version> <commit> -m \"Release <release-version>\"\n ```\n Replace `<release-version>` with the version number (e.g., `v1.2.3`) and `<commit>` with the commit hash of the merged pull request.\n - Push the tag to the remote repository:\n ```bash\n git push origin <release-version>\n ```\n\n3. **Create a GitHub Release:**\n - Open the [GitHub Releases page](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release).\n - Click \"Draft a new release.\"\n - In the **Tag version** field, select the previously pushed tag `<release-version>`.\n - Use `<release-version>` as the release title.\n - In the description, list the changes introduced in this release compared to the previous version.\n - Click \"Publish release.\"\n\n4. **Automatic Deployment:**\n - Once the release is published, GitHub Actions will automatically trigger the deployment process and publish the new version of the library to PyPI, as configured in the repository.\n",
"bugtrack_url": null,
"license": null,
"summary": "Codi Cooperatiu internal tools",
"version": "0.2.1",
"project_urls": {
"homepage": "https://github.com/codicoop/codi-cooperatiu-internal-tools",
"repository": "https://github.com/codicoop/codi-cooperatiu-internal-tools"
},
"split_keywords": [
"django",
" forms",
" flowbite"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "24afc678fcf6466f6eb781b58e51c6766178f75be348b98deeee44d8a8f4a6e5",
"md5": "89bfe026a14ed8606bf1264bff0d588e",
"sha256": "e7993d20e77c6270364048fc554ea667d47a53521860c422ddaeb385164cbafa"
},
"downloads": -1,
"filename": "codi_cooperatiu_internal_tools-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "89bfe026a14ed8606bf1264bff0d588e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 17346,
"upload_time": "2024-12-10T18:12:57",
"upload_time_iso_8601": "2024-12-10T18:12:57.296192Z",
"url": "https://files.pythonhosted.org/packages/24/af/c678fcf6466f6eb781b58e51c6766178f75be348b98deeee44d8a8f4a6e5/codi_cooperatiu_internal_tools-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "64886cfe5a0c8b06724dac77ceb04289ec5f8402d1e658b78dbd2428836f908b",
"md5": "53e99e0f5daed67de7d5cb24553534a4",
"sha256": "d375126b15a25577626db618721d38b6ed8c279775f89f69f07221bd53582a4a"
},
"downloads": -1,
"filename": "codi_cooperatiu_internal_tools-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "53e99e0f5daed67de7d5cb24553534a4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 12320,
"upload_time": "2024-12-10T18:12:59",
"upload_time_iso_8601": "2024-12-10T18:12:59.580832Z",
"url": "https://files.pythonhosted.org/packages/64/88/6cfe5a0c8b06724dac77ceb04289ec5f8402d1e658b78dbd2428836f908b/codi_cooperatiu_internal_tools-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-10 18:12:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "codicoop",
"github_project": "codi-cooperatiu-internal-tools",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "codi-cooperatiu-internal-tools"
}
JSON
