Package se.conciliate.extensions.publish

Interface FieldProvider<T>

All Known Subinterfaces:
ModelFieldProvider, VertexFieldProvider
public interface FieldProvider<T>
A field provider is a uniquely identifiable provider of field information. It is used to create custom publishing fields and to present those to the user. A field can have an icon, a title, a description, custom settings and a list of field contents.
It is strongly advised to only use immutable values in the settings map since its entries will be used on different threads and to make it clear when an entry changes.

Author's note:
I'm sorry that this API is as bad as it is. It is bad for two reasons, one being that the threading rules of the (existing) using objects is beyond poorly specified, the other being that the publishing is not built with plug-ins (through Java) in mind. Also, a third reason is "time constraints", also known as "path of least resistance" (or "I'm lazy"). To make this API properly, one would need to allocate a significant amount of work to re-design the using classes - an endeavour that would spiral up to the top of the module and certainly out to other modules (most notably custom-publish).
Author:
Per-Erik

  • Method Details

    • getContent

      List<FieldContent> getContent(T context)
      Returns a list of content for this field provider, based on the given context. To understand the context, please consult the specialised sub-interfaces. This interface is not intended to be implemented directly.
      Parameters:
      context - A context that is further specialised in sub-interfaces.
      Returns:
      A list of field contents.

    • getProviderID

      String getProviderID()
      Returns a unique ID for the field.
      Returns:
      A unique ID for the field. This is also used as the translation key to allow the user to translate the field heading in the HTML profile editor.

    • getStaticTitle

      String getStaticTitle()
      Returns the static title of this field provider. This is the title used for the provider itself.
      Returns:
      the static title of this field provider.

    • getStaticDescription

      String getStaticDescription()
      Returns the static description of this field provider. This is the description used for the provider itself.
      Returns:
      the static description of this field provider

    • getStaticIcon

      Icon getStaticIcon()
      Returns the static icon of this field provider. This is the icon used for the provider itself.
      Returns:
      the static icon of this field provider

    • getContentIcons

      Map<String,Icon> getContentIcons()
      Returns the icons needed to display the content of the field. These icons will be copied to the published material and can be used by providing the same name (including file extension) in the content.
      Returns:
      The icons needed in the content, mapped by file name.

    • getModelTypes

      Set<String> getModelTypes()
      Returns the ID:s of model types for which to show this information.
      Returns:
      A set of model type ID:s. If null or empty then the information will be shown regardless of model type.

    • hasSettings

      boolean hasSettings()
      Returns true if this field provider has settings that need to be saved as part of the profile, false otherwise.
      Note that settings will have no effect unless this field provider's content is a list of DOMFieldContent, other than possibly when viewing settings for a particular publishing. This is a limitation in the current way our CustomPublish works (which is a pure implementation note).

      Calling
      Thread: ui AND background thread
      Returns:
      true if this field provider has settings that need to be saved as part of the profile, false otherwise

    • getTitle

      String getTitle(Map<String,String> settings, MTLanguage lang)
      Returns the title of the field, possibly by using the settings. If the field can be translated, the implementation may use the lang parameter to make a translation (the translation may be based on either the iso language code, or the uuid of the lang parameter). Note that implementations are free to return the same title regardless of the lang parameter.

      NOTE: The map may be empty. This indicates that #getDefaultSettings returned an empty map (or that any of write, read or update failed for this field provider).

      Calling
      Thread: ui AND background thread
      Condition for calling: hasSettings() == true
      Parameters:
      settings - A settings map as produced by #read or #getDefaultSettings
      lang - The language of the title. Titles may be the same in every language. In such cases, this parameter may be ignored by implementations.
      Returns:
      the title of the field
      See Also:

    • getDescription

      String getDescription(Map<String,String> settings)
      Returns the description of the field, possibly by using the settings.

      NOTE: The map may be empty. This indicates that #getDefaultSettings returned an empty map (or that any of write, read or update failed for this field provider).

      Calling
      Thread: ui thread
      Condition for calling: hasSettings() == true
      Parameters:
      settings - A settings map as produced by #read or #getDefaultSettings
      Returns:
      The description of the field

    • getIcon

      Icon getIcon(Map<String,String> settings)
      Returns a tiny icon (16x16), possibly by using the settings, to be used in the HTML profile editor.

      NOTE: The map may be empty. This indicates that #getDefaultSettings returned an empty map (or that any of write, read or update failed for this field provider).

      Calling
      Thread: ui thread
      Condition for calling: hasSettings() == true
      Parameters:
      settings - A settings map as produced by #read or #getDefaultSettings
      Returns:
      A tiny icon (16x16)

    • getDefaultSettings

      Map<String,String> getDefaultSettings()
      Returns the default settings for this field provider. This method is guaranteed to be called before any of the methods taking a setting. This makes the method suitable to perform initialisation, if needed. If this is done, note that some methods taking a setting will be called from another thread than this method. This means that even if this method has been called, it is up to the implementation to make sure that any and all initialisation done is thread safe.

      Calling
      Thread: background thread
      Condition for calling: hasSettings() == true
      Returns:
      the default settings for this field provider.

    • read

      String read(Element settingElement)
      Returns a string corresponding to the given setting element. The returned string will be put as a value in a Map, with the key being the value of the element's "name"-attribute. It is therefore important that #write is correctly implemented to add the name attribute to elements.

      Calling
      Thread: background thread
      Condition for calling: hasSettings() == true
      Parameters:
      settingElement - The element to read
      Returns:
      The string read, based on the element
      See Also:

    • write

      void write(Element settingsElement, Map<String,String> settings)
      Writes new elements to the settingsElement, based on the settings map. The new elements must be on the form: 
        <setting name="KEY">VALUE</setting>
      where KEY indicates any name specific to this field provider and/or the setting to be saved. The name will be used when reading back the object. VALUE is a text node.
      This thus forms a key-value that, on read-back, is placed in a map where the key is the value of the name attribute and the value is the text value of the element.

      Calling
      Thread: background thread
      Condition for calling: hasSettings() == true
      Parameters:
      settingsElement - An element to put child elements in, where the direct child elements have the node name "setting" and each such "setting" has a name attribute.
      settings - A map from the setting-element's name-attributes to the object returned by read, or the default map returned by #getDefaultSettings.
      See Also:

    • update

      void update(Map<String,String> settings, JComponent c)
      Called to indicate that the user has validated the component c (the component returned from #getEditor) and thus, any changes made in the component needs to be written to the settings map.

      Calling
      Thread: ui thread
      Condition for calling: hasSettings() == true
      Parameters:
      settings - The map to update
      c - The component that the update is based on. This is the component returned from #getEditor.

    • getEditor

      JComponent getEditor(Map<String,String> settings)
      Returns a component used to edit the given settings. The settings are constructed using #read (or #getDefaultSettings).

      Calling
      Thread: ui thread
      Condition for calling: hasSettings() == true
      Parameters:
      settings - The settings to edit.
      Returns:
      A JComponent to edit the given settings.
      See Also: