# AttachmentField

An Archetype field that manages file attachments, to be used in place of a FileField.

AttachmentField allows you to index and preview various kinds of documents, such as MSOffice (Word, Excel, Powerpoint), PDF and more in your Archetypes based content types.

This product replaces the former ZAttachmentAttribute from Ingeniweb (see ingeniweb.sourceforge.net).

Be sure to read the warnings below before using it.

# Warning

- Due to lots of misuses of AttachmentField, be warned that it does not

System Message: WARNING/2 (`<string>`, line 21)

Bullet list ends without a blank line; unexpected unindent.

add any new content type by itself. AttachmentField is a product for Plone/Archetypes content types developers.

- It is strongly discouraged to uninstall AttachmentField while configured to

System Message: WARNING/2 (`<string>`, line 25)

Bullet list ends without a blank line; unexpected unindent.

use FileSystemStorage. If so, all contents that use AttachmentField would be lost (even if you reinstall it later). If you want to upgrade, just reinstall it without uninstalling it.

If you need to uninstall AttachmentField, first configure it to use AttributeStorage (in ZODB) (default choice). In this case, you can then uninstall AttachmentField without loosing your content (You will need to reinstall a version of AttachmentField to access them again)

# Dependencies

## Python packages

- python-libxml2
- python-libxslt

You need these packages for OpenOffice documents support.

These Python extensions are available as packages in most Linux distros. Windows users may find a suitable libxml2 + libxslt for Python installer from http://users.skynet.be/sbi/libxml-python/

## Zope/Plone

- Plone 2.1.x
- Archetypes 1.3.7+
- FileSystemStorage (only if you want to use FSS)

## Applications/utilities (Unix)

- xpdf >= 3.0
- wvware >= 1.0
- xlhtml
- ppthtml
- unrtf >= 0.19

## Applications/utilities (win32)

All above listed binary plugins are provided "batteries included" for Windows,

# The improvements / regressions of AF over ZAA are:

- AF uses Archetypes' Field design to work. It's, then, Archetypes-dependent.
- ZAAPlugins is no longer necessary. All AF plugins are integrated directly into the AF product.
- AF offers a convenient plugin structure, allowing you to create plugins with only 10 lines of code. Doing so, we've lost a little bit of the flexibility we never needed ;) However it's still possible to override the AttachmentHandler class to offer more flexibility (AttachmentHandler is the new name for AbstractAttachment).
- A plugin is now a singleton providing indexing & preview & iconing services. No more polymorphism as in ZAA (in ZAA, each and every attachement stored an instance of a plugin class, which turned out to be too complicated for the actual need).
- A side effect of the preceding point is that you can upload invalid files to your server and develop (or configure) new plugins AFTER you've uploaded 'em. AF will dynamically detect the new content type and will provide preview and indexing support magically. With that feature, customers can start populating a website very early in the process!
- AF doesn't support images in MSWord preview yet (it will !)
- AF doesnt' store attachments preview nor searchable text in ZODB; they are cached though, and will normally be calculated only once per Zope program run. This may be configurable in the future (ie. you can choose best speed or less disk usage).

# Example of use in a AT content type source

We assume you really know Archetypes to understand this simple example...

    from Products.AttachmentField.AttachmentField import AttachmentField
    from Products.AttachmentField.AttachmentWidget import AttachmentWidget
    ...
    my_schema = Schema((
        ...
        AttachmentField('someFile'
                         searchable=True,
                         primary=True,
                         widget=AttachmentWidget(label="White paper",
                                                 description="Your white paper for this topic",
                                                 show_content_type=True)
                         )
        ...
        ))
    ...

# Testing

## Unit tests

Install PloneTestCase on your instance

> use testrunner -qad .

## Configlet

Plone managers can test the AttachmentField with the dedicated configlet.

# Credits

AttachmentField is an Ingeniweb product.

AttachmentField embeds Win32 versions of file transformation utilities. Many thanks to the authors and maintainers of following products:

- wvWare: http://wvware.sourceforge.net/
- xpdf (Glyph & Cog, LLC. / Foolabs): http://www.foolabs.com/xpdf/download.html
- xlhtml and ppthtml (Wrensoft): http://www.wrensoft.com/zoom/plugins.html
- unrtf: http://gnuwin32.sourceforge.net/packages/unrtf.htm

Some of theses tools require a special version of cygwin1.dll you an find in the unrtf directory.

# License

AttachmentField is protected by the terms of the GPL v2 license. See the LICENSE file for details.

# Downloads

You may find newer stable versions of AttachmentField and pointers to related informations (tracker, doc, ...) from http://plone.org/products/attachmentfield

# SVN repository

Stay in tune with the freshest (unstable) versions or participate to the AttachmentField maintenance:

https://svn.plone.org/svn/collective/AttachmentField

# Feedback

Report bugs at http://sourceforge.net/projects/ingeniweb (click the "Bugs" link)

Ask for support at support@ingeniweb.com

[TODO]

- Dependencies in the documentation (archetypes, external programs, ...)
- MSWord images support
- Support additional preview for mp3, images, ...
- Add MD5 to check files are not corrupted

## 1.4.5 - 2012-09-10

- PyPI release [aclark]

## 1.4.4 - 2008-05-21

- Fix the getTransforms method in PortalTransformsAttachment, which didn't find text/plain transforms under certain circumstances due to a wrong indentation and a try: except that included two distict cases. (maikroeder) 2008-05-07

## 1.4.3 - 2007-08-27

- Fix bug with Zope External Editor 0.9.x: the filename was replaced by the id. This bug is in the ZEE client and would not be fixed soon (encolpe)

## 1.4.2 - 2007-08-20

- Fixed unit tests (glenfant)
- Cleanup of duplicated win32 helper apps (glenfant))
- Changed win32 ppthtml and xlhtml against newer/safer versions from Wrensoft http://www.wrensoft.com/zoom/plugins.html (glenfant)
- Upgraded win32 xpdf (3.0.2) from Foolabs http://www.wrensoft.com/zoom/plugins.html (glenfant)
- Fixed encoding to UTF-8 for Excel and Powerpoint attachments because Xlhtml returns always UTF-8. (zegor)

## 1.4.1 - 2007-06-04

- Using canonical logging API (see http://docs.python.org/lib/node406.html) (glenfant)
- Warnings raised real exceptions and prevented to index/preview Word 2003 docs under Windows. (glenfant)
- Icons are now only computed during the first call (zegor)
- Migration to FileSystemStorage now migrates PloneArticle Attachments (zegor)

## 1.4 - 2007-04-19

- Remove dead and dangerous code (_process_input, mimetypes stuffs, etc)
- Enhance AF widget (remove useless parentheses)

## 1.3.13 - 2007-03-14

- Fixed savepoint argument for Zope 2.7 in flexstorage (zegor)

- Left align, added margin and close button in preview_popup (zegor)

- Optimizations (zegor)
    - PreviewAvailable and isIndexable methods uses booleans instead of testing "huge" strings
    - Preview and indexable attributes are now only computed during the first call
    - Fixed ZODB transactions on each call when content is not indexable

## 1.3.12 - 2007-02-13

- FlexStorage: do sub-commits during storage migration
- reintroduced _process_input (temp fix for icon/mimetype problems)
- removed field external editor

## 1.3.11 - 2006-10-26

- Fix a bug that broke the configlet generation on Windows.
- Added PSAttachment (based on pstotext) (thanks to ajung)
- Use python logging. Requires Zope 2.8+

## 1.3.10 - 2006-09-19

- Fix a security hole (inlined text/*)

  System Message: WARNING/2 (`<string>`, line 304); backlink

  Inline emphasis start-string without end-string.

- Fix SF bug #1542861

- Update the setHeader content...

## 1.3.9 - 2006-07-31

- Fix broken installation method (thanks to adf)

## 1.3.8 - 2006-07-25

- introduce the flex storage that allow attachment field to store its content to be stored either in ZODB or with FSS.

## 1.3.7 - 2006-07-10

- fix #1505660 (sourceforge): import statement in OOConverter (2006-06-14 BM)
- add inline (or attachment) view

## 1.3.6 - 2006-06-08

- Ignore images in MSWord. Added option "-1" to wvWare.exe (2006-06-08 MR)
- Limit maximum cols and rows for Excel to 100. Configurable in global_symbols.py (2006-06-08 MR)

## 1.3.5 - 2006-05-14

- Use of global external editor link and webdav lock (yeah)
- Removed Extenal Editor link (cannot work at field level)
- Fixed mime-type classification (MS Excel and Powerpoint processed as MS Word docs)

## 1.3.4 - 2006-05-2

- Add base compatibility with CompoundField product (2006-03-15 ED)
- Fix lack of permissions when running unit tests (2006-03-15 ED)
- Added Photoshop attachment plugin

## 1.3.3 - 2006-01-24

- Fixed attachment recognition issue with Plone 2.1.2

[1.3.1 - 20060113]

- OpenOffice2 documents support
- Fix widget: only a single file input is shown if field is empty. Also fixes "first upload without deletion" (2005-12-15 BM)

[v1.3 - 20051102]

- First upload without deletion, replacement and unchanged check boxes. (2005-10-31 MR)
- Better log in case of missing libxml2 or libxslt (2005-09-06 MR)
- Added a Flash attachment plug-in (thanks to Harlow Pinson)
- Fix a bug from AT update schemas method - ED

[v1.3RC5 - 20050832]

- Removed AttachementService; use the configlet in plone control panel instead
- Fix an infinite loop which was hanging Zope at 100% CPU

[v1.3RC4 - 20050729]

- Fixing bug in download method of AttachmentField using FileField instead of Field.FileField

[v1.3RC3 - 20050524]

- Supports correctly MSWord again under Win32
- Fixed Installer to uninstall configlet
- Fixed an unicode bug with PortalTransformsAttachment
- Provided a regex-based HTML stripper, especially for wvWare output
- Added RTF attachments support
- Uses Mimetypesregistry as a fallback to index RTF stuff
- OpenOffice documents are now natively indexed

[v1.3RC2 - 20050325]

- Little fix with PortalTransofrms under win32
- Uses a typeless content type to generate the configlet sample page

[v1.3RC1 - 20050322]

- Fixed icon for unknown content types (interrogation mark instead of RTF icon)
- Added a 'PortalTransformAttachment' class which is able now to use PortalTransforms as an attachment service. Wow! Tested, for example, with CMFOODocument.
- Added support for compressed files (zip, rar, ...) thanks to Zegor

[v1.2 - 20050311]

- Add AttachmentWidget
- Added video files support

[v1.1 - 20050225]

- Improved temporary files management. Now all converter output should be written in a temporary directory.

[v1.0 - 20050118]

- Code page translation in the callConverter()-like methods
- Archetypes' automatic SearchableText support (contentType argument in get(), AND 'searchable' field parameter support; eg. we'd disable automatic indexing if 'searchable' is false).
- Created an AttachmentService to test and monitor stuff.
- Created an AttachmentTool for Plone and a configlet to monitor stuff.

[v1.0RC - 20041229]

- Making isEmpty method of AttachmentField a bit safer 2004/12/29 MR
- Fixed problem with paths under Windows 2004/12/29 MR
- Fixed close of open file problem 2004/12/29 MR
- First version ! ;)