Metadata-Version: 2.1
Name: odoo-addon-fs_image
Version: 18.0.1.0.0.4
Requires-Python: >=3.10
Requires-Dist: odoo-addon-fs_file==18.0.*
Requires-Dist: odoo==18.0.*
Summary: Field to store images into filesystem storages
Home-page: https://github.com/OCA/storage
License: AGPL-3
Author: ACSONE SA/NV,Odoo Community Association (OCA)
Author-email: support@odoo-community.org
Classifier: Programming Language :: Python
Classifier: Framework :: Odoo
Classifier: Framework :: Odoo :: 18.0
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Development Status :: 3 - Alpha
Description-Content-Type: text/x-rst

.. image:: https://odoo-community.org/readme-banner-image
   :target: https://odoo-community.org/get-involved?utm_source=readme
   :alt: Odoo Community Association

========
Fs Image
========

.. 
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! This file is generated by oca-gen-addon-readme !!
   !! changes will be overwritten.                   !!
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! source digest: sha256:0bfa62822ec06f1676a3d3add23904556a8af702066a613604e58c2062e65540
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

.. |badge1| image:: https://img.shields.io/badge/maturity-Alpha-red.png
    :target: https://odoo-community.org/page/development-status
    :alt: Alpha
.. |badge2| image:: https://img.shields.io/badge/license-AGPL--3-blue.png
    :target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
    :alt: License: AGPL-3
.. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fstorage-lightgray.png?logo=github
    :target: https://github.com/OCA/storage/tree/18.0/fs_image
    :alt: OCA/storage
.. |badge4| image:: https://img.shields.io/badge/weblate-Translate%20me-F47D42.png
    :target: https://translation.odoo-community.org/projects/storage-18-0/storage-18-0-fs_image
    :alt: Translate me on Weblate
.. |badge5| image:: https://img.shields.io/badge/runboat-Try%20me-875A7B.png
    :target: https://runboat.odoo-community.org/builds?repo=OCA/storage&target_branch=18.0
    :alt: Try me on Runboat

|badge1| |badge2| |badge3| |badge4| |badge5|

This addon defines a new field **FSImage** to use in your models. It is
a subclass of the **FSFile** field and comes with the same features. It
extends the **FSFile** field with specific properties dedicated to
images. On the field definition, the following additional properties are
available:

- **max_width** (int): maximum width of the image in pixels (default:
  ``0``, no limit)
- **max_height** (int): maximum height of the image in pixels (default:
  ``0``, no limit)
- **verify_resolution** (bool):whether the image resolution should be
  verified to ensure it doesn't go over the maximum image resolution
  (default: ``True``). See odoo.tools.image.ImageProcess for maximum
  image resolution (default: ``50e6``).

On the field's value side, the value is an instance of a subclass of
odoo.addons.fs_file.fields.FSFileValue. It extends the class to allows
you to manage an alt_text for the image. The alt_text is a text that
will be displayed when the image cannot be displayed.

.. IMPORTANT::
   This is an alpha version, the data model and design can change at any time without warning.
   Only for development or testing purpose, do not use in production.
   `More details on development status <https://odoo-community.org/page/development-status>`_

**Table of contents**

.. contents::
   :local:

Usage
=====

This new field type can be used in the same way as the odoo 'Image'
field type.

.. code:: python

   from odoo import models
   from odoo.addons.fs_image.fields import FSImage

   class MyModel(models.Model):
       _name = 'my.model'

       image = FSImage('Image', max_width=1920, max_height=1920)

.. code:: xml

   <record id="my_model_form" model="ir.ui.view">
       <field name="name">my.model.form</field>
       <field name="model">my.model</field>
       <field name="arch" type="xml">
           <form>
               <sheet>
                   <group>
                       <field name="image" class="oe_avatar"/>
                   </group>
               </sheet>
           </form>
       </field>
   </record>

In the example above, the image will be resized to 1920x1920px if it is
larger than that. The widget used in the form view will also allow the
user set an 'alt' text for the image.

A mode advanced and useful example is the following:

.. code:: python

   from odoo import models
   from odoo.addons.fs_image.fields import FSImage

   class MyModel(models.Model):
       _name = 'my.model'

       image_1920 = FSImage('Image', max_width=1920, max_height=1920)
       image_128 = FSImage('Image', max_width=128, max_height=128, related='image_1920', store=True)

.. code:: xml

   <record id="my_model_form" model="ir.ui.view">
       <field name="name">my.model.form</field>
       <field name="model">my.model</field>
       <field name="arch" type="xml">
           <form>
               <sheet>
                   <group>
                       <field
                           name="image_1920"
                           class="oe_avatar"
                            options="{'preview_image': 'image_128', 'zoom': true}"
                        />
                   </group>
               </sheet>
           </form>
       </field>
   </record>

In the example above we have two fields, one for the original image and
one for a thumbnail. As the thumbnail is defined as a related stored
field it's automatically generated from the original image, resized at
the given size and stored in the database. The thumbnail is then used as
a preview image for the original image in the form view. The main
advantage of this approach is that the original image is not loaded in
the form view and the thumbnail is used instead, which is much smaller
in size and faster to load. The 'zoom' option allows the user to see the
original image in a popup when clicking on the thumbnail.

For convenience, the 'fs_image' module also provides a 'FSImageMixin'
mixin class that can be used to add the 'image' and 'image_medium'
fields to a model. It only define the medium thumbnail as a 128x128px
image since it's the most common use case. When using an image field in
a model, it's recommended to use this mixin class in order ensure that
the 'image_medium' field is always defined. A good practice is to use
the image_medium field as a preview image for the image field in the
form view to avoid to overload the form view with a large image and
consume too much bandwidth.

.. code:: python

   from odoo import models

   class MyModel(models.Model):
       _name = 'my.model'
       _inherit = ['fs_image.mixin']

.. code:: xml

   <record id="my_model_form" model="ir.ui.view">
       <field name="name">my.model.form</field>
       <field name="model">my.model</field>
       <field name="arch" type="xml">
           <form>
               <sheet>
                   <group>
                       <field
                           name="image"
                           class="oe_avatar"
                           options="{'preview_image': 'image_medium', 'zoom': true}"
                       />
                   </group>
               </sheet>
           </form>
       </field>
   </record>

Changelog
=========

16.0.1.0.3 (2024-02-23)
-----------------------

**Bugfixes**

- (`#305 <https://github.com/OCA/storage/issues/305>`__)

16.0.1.0.2 (2023-12-02)
-----------------------

**Bugfixes**

- Fix view crash when uploading an image

  The rawCacheKey is appropriately managed by the base class and
  reflects the record's last update datetime (write_date). Since it
  lacks a setter, attempting to invalidate its value results in a view
  crash. Nevertheless, the value will automatically be updated upon
  saving the record.
  (`#305 <https://github.com/OCA/storage/issues/305>`__)

16.0.1.0.1 (2023-12-02)
-----------------------

**Bugfixes**

- Avoid to generate an SQL update query when an image field is read.

  Fix a bug in the initialization of the image field value object when
  the field is read. Before this fix, every time the value object was
  initialized with an attachment, an assignment of the alt text was done
  into the constructor. This assignment triggered the mark of the field
  as modified and an SQL update query was generated at the end of the
  request. The alt text in the constructor of the FSImageValue class
  must only be used when the class is initialized without an attachment.
  We now check if an attachment and an alt text are provided at the same
  time and throw an exception if this is the case.
  (`#307 <https://github.com/OCA/storage/issues/307>`__)

Bug Tracker
===========

Bugs are tracked on `GitHub Issues <https://github.com/OCA/storage/issues>`_.
In case of trouble, please check there if your issue has already been reported.
If you spotted it first, help us to smash it by providing a detailed and welcomed
`feedback <https://github.com/OCA/storage/issues/new?body=module:%20fs_image%0Aversion:%2018.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.

Do not contact contributors directly about support or help with technical issues.

Credits
=======

Authors
-------

* ACSONE SA/NV

Contributors
------------

- Laurent Mignon <laurent.mignon@acsone.eu>
- Nguyen Minh Chien <chien@trobz.com>
- Denis Roussel <denis.roussel@acsone.eu>

Maintainers
-----------

This module is maintained by the OCA.

.. image:: https://odoo-community.org/logo.png
   :alt: Odoo Community Association
   :target: https://odoo-community.org

OCA, or the Odoo Community Association, is a nonprofit organization whose
mission is to support the collaborative development of Odoo features and
promote its widespread use.

.. |maintainer-lmignon| image:: https://github.com/lmignon.png?size=40px
    :target: https://github.com/lmignon
    :alt: lmignon

Current `maintainer <https://odoo-community.org/page/maintainer-role>`__:

|maintainer-lmignon| 

This module is part of the `OCA/storage <https://github.com/OCA/storage/tree/18.0/fs_image>`_ project on GitHub.

You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.
