Back to index

plone3  3.1.7
_field.py
Go to the documentation of this file.
00001 from zope.interface import Interface, Attribute
00002 
00003 class IField(Interface):
00004     """ Interface for fields """
00005 
00006 #     required = Attribute('required', 'Require a value to be present when submitting the field')
00007 #     default = Attribute('default', 'Default value for a field')
00008 #     default_method = Attribute('default_method', 'Name of a method on the field ' + 
00009 #                                                  'or an actual function instance to return the default')
00010 #     vocabulary = Attribute('vocabulary', 'List of suggested values for the field')
00011 #     vocabulary_factory = Attribute('vocabulary_factory', 'Name of Zope 3 vocabulary factory')
00012 #     enforceVocabulary = Attribute('enforceVocabulary', \
00013 #                                   'Restrict the allowed values to the ones in the vocabulary')
00014 #     multiValued = Attribute('multiValued', 'Allow the field to have multiple values')
00015 #     searchable = Attribute('searchable', 'Make the field searchable')
00016 #     isMetadata = Attribute('isMetadata', 'Is this field a metadata field?')
00017 #     accessor = Attribute('accessor', 'Use this method as the accessor for the field')
00018 #     mutator = Attribute('mutator', 'Use this method as the mutator for the field')
00019 #     mode = Attribute('mode', 'Mode of access to this field')
00020 #     read_permission = Attribute('read_permission', \
00021 #                                 'Permission to use to protect field reading')
00022 #     write_permission = Attribute('write_permission', \
00023 #                                  'Permission to use to protect writing to the field')
00024 
00025 #     storage = Attribute('storage', 'Storage class to use for this field')
00026 #     form_info = Attribute('form_info', 'Form Info (?)')
00027 #     generateMode = Attribute('generateMode', 'Generate Mode (?)')
00028 #     force = Attribute('force', 'Force (?)')
00029 #     type = Attribute('type', 'Type of the field')
00030 
00031     def Vocabulary(content_instance=None):
00032         """
00033         returns a DisplayList
00034 
00035         uses self.vocabulary as source
00036 
00037         1) Dynamic vocabulary:
00038 
00039             precondition: a content_instance is given.
00040 
00041             has to return a:
00042                 * DisplayList or
00043                 * list of strings or
00044                 * list of 2-tuples with strings:
00045                     '[("key1","value 1"),("key 2","value 2"),]'
00046 
00047             the output is postprocessed like a static vocabulary.
00048 
00049             vocabulary is a string:
00050                 if a method with the name of the string exists it will be called
00051 
00052             vocabulary is a class implementing IVocabulary:
00053                 the "getDisplayList" method of the class will be called.
00054 
00055 
00056         2) Static vocabulary
00057 
00058             * is already a DisplayList
00059             * is a list of 2-tuples with strings (see above)
00060             * is a list of strings (in this case a DisplayList with key=value
00061               will be created)
00062 
00063         3) Zope 3 vocabulary factory vocabulary
00064         
00065             - precondition: a content_instance is given
00066             
00067             - self.vocabulary_factory is given
00068             
00069             - a named utility providing zope.schema.interfaces.IVocbularyFactory 
00070               exists for the name self.vocabulary_factory.     
00071 
00072         """
00073 
00074     # private
00075     def copy():
00076         """Return a copy of field instance [PRIVATE]
00077 
00078         Consisting of field name and properties dictionary.
00079         """
00080 
00081     def validate(value, instance, errors={}, **kwargs):
00082         """Validate passed-in value using all field validators.
00083 
00084         Return None if all validations pass; otherwise, return failed
00085         result returned by validator
00086         """
00087 
00088     # private
00089     def validate_required(instance, value, errors):
00090         """Validate the required flag for a field [PRIVATE]
00091 
00092         Overwrite it in your field for special case handling like empty files
00093         """
00094 
00095     def checkPermission(mode, instance):
00096         """
00097         Check whether the security context allows the given permission on
00098         the given object.
00099 
00100         Arguments:
00101 
00102         permission -- A permission name
00103         instance -- The object being accessed according to the permission
00104         """
00105 
00106     def checkExternalEditor(instance):
00107         """ Checks if the user may edit this field and if
00108         external editor is enabled on this instance
00109         """
00110 
00111     def getWidgetName():
00112         """Return the widget name that is configured for this field as
00113         a string"""
00114 
00115     def getName():
00116         """Return the name of this field as a string"""
00117 
00118     def getType():
00119         """Return the type of this field as a string"""
00120 
00121     def getDefault(instance):
00122         """Return the default value to be used for initializing this
00123         field"""
00124 
00125     def getAccessor(instance):
00126         """Return the accessor method for getting data out of this
00127         field"""
00128 
00129     def getEditAccessor(instance):
00130         """Return the accessor method for getting raw data out of this
00131         field e.g.: for editing
00132         """
00133 
00134     def getMutator(instance):
00135         """Return the mutator method used for changing the value
00136         of this field"""
00137 
00138     # private
00139     def toString():
00140         """Utility method for converting a Field to a string [PRIVATE]
00141 
00142         For the purpose of comparing fields.  This comparison is used for
00143         determining whether a schema has changed in the auto update
00144         function.  Right now it's pretty crude."""
00145 
00146     def isLanguageIndependent(instance):
00147         """Get the language independed flag for i18n content (used by LinguaPlon)
00148         """
00149 
00150 
00151 class IObjectField(IField):
00152     """ Interface for fields that support a storage layer """
00153 
00154     # private
00155     def get(instance, **kwargs):
00156         """Get the value for this field using the underlying storage [PRIVATE]
00157         """
00158 
00159     # private
00160     def getRaw(instance, **kwargs):
00161         """Get the raw value for this field using the underlying storage [PRIVATE]
00162         """
00163 
00164     # private
00165     def set(instance, value, **kwargs):
00166         """Set the value for this field using the underlying storage [PRIVATE]
00167         """
00168 
00169     # private
00170     def unset(instance, **kwargs):
00171         """Unset the value for this field using the underlying storage [PRIVATE]
00172         """
00173 
00174     # private
00175     def getStorage():
00176         """Return the storage class used in this field [PRIVATE]
00177         """
00178 
00179     # private
00180     def setStorage(instance, storage):
00181         """ Set the storage for this field to the give storage. [PRIVATE]
00182 
00183         Values are migrated by doing a get before changing the storage
00184         and doing a set after changing the storage.
00185 
00186         The underlying storage must take care of cleaning up of removing
00187         references to the value stored using the unset method."""
00188 
00189     def getStorageName(instance=None):
00190         """Return the storage name that is configured for this field
00191         as a string"""
00192 
00193     def getStorageType(instance=None):
00194         """Return the type of the storage of this field as a string"""
00195 
00196     def getContentType(instance, fromBaseUnit=True):
00197         """Return the mime type of object if known or can be guessed;
00198         otherwise, return None."""
00199 
00200     def get_size(instance):
00201         """Get size of the stored data used for get_size in BaseObject
00202         
00203         Should be overwritte by special fields like FileField. It's safe for
00204         fields which are storing strings, ints and BaseUnits but it won't return
00205         the right results for fields containing OFS.Image.File instances or
00206         lists/tuples/dicts.
00207         """
00208 
00209 class IFileField(IObjectField):
00210     """Interface fora fields which (may) contain a file like FileField or
00211     TextField
00212     """
00213 
00214     #content_class = Attribute("""Class that is used to wrap the data like
00215     #                              OFS.Image.File for FileField"""
00216 
00217     # private
00218     def _process_input(value, default=None, mimetype=None, **kwargs):
00219         """Processes user input [PRIVATE]
00220 
00221         Must take care of:
00222             * string
00223             * open files
00224             * FileUpload
00225             * open file like things
00226             * BaseUnit
00227             * maybe more ...
00228         """
00229 
00230     # private
00231     def getBaseUnit(instance):
00232         """Return the value of the field wrapped in a base unit object [PRIVATE]
00233         """
00234 
00235     def getFilename(instance, fromBaseUnit=True):
00236         """Get file name of underlaying file object
00237         """
00238 
00239     # private
00240     def setFilename(instance, filename):
00241         """Set file name in the base unit [PRIVATE]
00242         """
00243 
00244     # private
00245     def download(instance):
00246         """Kicks download [PRIVATE]
00247 
00248         Writes data including file name and content type to RESPONSE
00249         """
00250 
00251 class IImageField(IFileField):
00252     """ Marker interface for detecting an image field """
00253 
00254 class IFieldDefaultProvider(Interface):
00255     """Register a named adapter for your content type providing
00256     this interface, with a name that is equal to the name of a
00257     field. If no default or default_method is set on that field
00258     explicitly, Archetypes will find and call this adapter.
00259     """
00260     
00261     def __call__():
00262         """Get the default value.
00263         """