[[BackLinksMenu]]

[[TicketQuery(summary=RESOURCES_EXPORT_IMPORT_R0, format=table, col=summary|owner|status|type|component|priority|effort|importance, rows=description|analysis_owners|analysis_reviewers|analysis_score|design_owners|design_reviewers|design_score|implementation_owners|implementation_reviewers|implementation_score|test_owners|test_reviewers|test_score|)]]

= Analysis =
^(Give as much as possible of the needed information for designing and implementing the task in the following sections.)^

== Overview ==
The resource palette consist of only frame contents (Discussion with Milo : And here we will have advanced 'mode' with the other resources again...). These frames include all the frames which can be inserted without the browser frame. All The resources can be imported and exported as while exporting, the elements are exported in the corresponding format(if jpg, in jpg; if pdf in pdf; if sjrb, in sjrb and so on). 
The other goal of this revision is to support import multiple files at once.

== Task requirements ==
 * Add support for selecting multiple items in the file dialogs
  * This should allow importing a lot of image or other media resources at once. 
 * Create an ability for importing any resource.
  * The "Import" from resources palette should open a file dialog
  * The file dialog dropdown should have 1 entry - All files (*.*) - This is for now, later "Image", "Audio", etc things should be added.
  * The tooltip should say "Import any kind of supported resource, folder or zip with resources."
  * When a folder is selected the button should not change to "Open" like it does in the other file dialogs. Import should be available instead, which should allow import of a folder with resources
   * zip files should be scanned for resources and they should be added to the list with the resources. This should be done carefully, because Sophie internal resources are in zips too. 
   * For both, folder and zip, only their supported contents should be added. But if the user has selected an unsupported file, he should be warned by a message box. If multiple files are selected and part of them are unsupported the user should be notified about them, and the supported ones should be imported.
 * Add support feature
  * Every resource is exported in the corresponding format (Discussion with Milo : No, here we can save resources to our format or other formats, the file save dialog will give us choices, and the DND will export will depend on where we drop : word/notepad/Desktop...).
  * The "Import" from resources palette should open a file dialog with "All files" entry and correct name suggested. (the same name as the resource)
  * (Optional) Multiple export should only ask for folder to export the resources. Not required for this revision 
  * Texts and comments are exported in rtf format (Discussion with Milo : Here again we will export to our format or some other depending on the DND target/choosen in the File save dialog). 
  * All the imported resources are not inserted on the page work area but only in the resources palette and can be inserted in the page by drag and drop (Drag and drop is not part of this task). 
  * (optioanal) Resources can be exported and imported by drag and drop
 * Change the filters in the resources palette - replace them with icons, see implementation idea
  * Remove pages, frames and templates from this view
  * Add icon filters for
   * text
   * image
   * audio
   * video
   * pdf
   * script
  * Take in mind that other things will be needed in future - flash for example
== Task result ==
Source code

== Implementation idea ==
    * Make file dialog to support multiple selection and provide a logic that will handle it.
    * Add new file dialog that can open files and directories. When the user select something: 

        1 If it is a file, try to open it

            1.2 If it is a zip file, decompress it and go to 1

        2 If it is a directory list its files

            2.1 If there are only files go to 1

            2.2 If there are directories go to 2

    * Create something like ResourceManipuationProvider, which will be used for easier and centralized import of resources, for example with it will be registered the corresponding insert menus and will be used for both inserting resources with frames and importing them.
    * Modify the FileDialogInput to work with folders.
    * Add logic for decompressing or browsing zip files
    * Try to fix the RTF export/import of the text to take in mind styles (optional because it could be time taking).

[[Image(resources.jpg)]]


== Related ==
APP_RESOURCE_LIST_IMPORT_EXPORT_R0 [[BR]]
APP_RESOURCE_LIST_IMPORT_EXPORT_R1

== How to demo ==
   1. Create a book
   2. Go to insert menu, choose Image..., and select 2 images in jpeg format by using ctrl+click and notice they are inserted at the one and same time.
   3. Export one of the pictures and notice it is exported in jpeg format.
   4. Insert a text frame.
   5. Export the text frame and notice it is in rtf format.
   6. Choose insert -> Any resource
   8. Select the folder and click insert. Notice all the familiar format files from the folder are inserted. 

= Design =
 * We need to enable the FileDialog to use the mode JFileChooser.FILES_AND_DIRECTORIES when the dialog is shown with multy-select enabled. Every time the dialog is shown with enabled multy select we will be able to choose both directories and multiple files. Another change is that FileDialogInput.FileContainer should return list of all files in the directoriy trees choosed flatten. Importing of all kind of resources from files will be done with FileDialogs with multiple selection enabled.
 * Importing resources: Importing of resources has to have one centralized logic. There are three kinds of import - importing resource, importing resource and inserting frame for it and inserting frame for already imported resource.
  * The import interfaces and base implementations will be in the {{{org.sophie2.main.func.resources module}}} in a packqge called 'imports'. It can not be 'import' because this is a key word in java.
  * ResourceImportProvider. In the {{{org.sophie2.main.func.resources}}} module there will be an extension points for resource import providers. The providers will have to be easy to find and have to provide many different ways for that. For example we want to find provider by the import role of some insert menu item, or by the FileFilter of some dialog or by the resource kind... So there will be such providers that can provide something called ResourceImportManager which is used for the import itself. I divided the manager into a manager and provider, because I wanted to take out the extension registering and searching logic from the huge manager.
   * SimpleResourceImportProvider : Added for easy registering of import providers. Default implementation and have method {{{register}}} that registers provider by it's import manager and file filter. The filter can be null if the ImportManager don't use files to import. This implementation also has method {{{getProvider}}} that takes instance of class called ProviderMatcher as parameter. This matcher has abstract method can be used to match a provider by one or more different characteristics... Used for easy matching the right provider when needed.
  * ResourceImportManager. The manager will handle importing of resources. Some of the routines while importing are the same so the manager will be abstract class with default implementations for them. Every importable resource will have implementation of the manager. The implementations will provide some meta data needed for the import and methods for creating the resource and retrieving its data from different sources like files for example. The managers are immutable and generic for the resource data type (For example ImmImage for image resource). Methods of the ResourceImportManager are:
   * {{{String getImportRole()}}} : Abstract method which provides import role, these roles are used for retrieving the right manager for the right resource  import. For example when we import image we have something like import image role.
   * {{{String getResourceKind()}}} : Abstract method that provides the kind of the resource of the manager.
   * {{{ResourceRefR4 generateChildRef()}}} : Method using generics to create good child reference for the right resource kind... Not needed but helps a lot for readable refs.
   * {{{List<ResourceImportInfo> retrieveResourceInfo(ResourceImportProvider provider)}}} : That method have default implementation. The ResourrceImportInfo is container for the sata needed to create given resource. For example the image resource have ImmImmage as a data, some title and import origin URI... The default implementation of the method brings up FileDialog with filter, the provided filter by the provider and the creates the ResourceImportInfos for every chosen file.
   * {{{D getResourceData}}} methods : they are three and only one of them is mandatory to write in the implementations. The mandatory one is with parameter File, the other two with parameters ResourceAccess and DndTransferable. The data for the resource can be received from a file or from a resource access from file in Sophie Format, memory resource, server resource, etc.. or from dropping a transferable, and that is the purpose of these methods.
   * {{{String getFrameKind()}}} : Gives the kind of the frame that the manager can insert for it's resource. Abstract.
   * {{{ImmSize computeFrameSize(D data)}}} : Many resources compute their frames size in different ways so that methods is necessary, by default it returns the default frame size.
   * {{{void insertFrame(...)}}} Inserts frame, and because the logic for inserting frames is the same for every resource it is implemented in the base class.
  * For every importable resource there will be ResourceImportManager implementation and all the repeated logic in the modules for inserting and importing will be removed. There is one spesial SophieFormatImportManager that imports resources into Sophie 2.0 format... It is special because all the resources are able to be imported with it. For resources that have no special data like the Browser there is EmptyDataImportManager to be extended by them.
  * ResourceImportUtil : The util provides methods that can insert frame and create resource, import resources, insert frames for existing resources and is able to handle dropped resources from the DND. These methods work with the appropriate provider and additional parameters like current book for example.
  * ResourceImportLogic : This logic handles all the imports of resources in Sophie 2. It uses the ResourceImportUtil's methods. Handlers:
   * ON_INSERT_FRAME : Handles inserting frames from the menu items. All the menu items that insert resources extend InsertResourceMenuItem which have abstract method getImportRole. That means that every insert item has such a role, and the right ResourceImportProvider for it can be found easily. The items have isLinked method too, So the logic works in the following way : Fetches the right provider by the import role of the InsertMenuItem, source of the event and if it doesn't insert linked frame creates the right resource. Inserts frame for the link or the resource.
   * ON_IMPORT_RESOURCE : It's event's source is the ResourceDetailsPalette, the import button... It simply opens FileDialog with all files filter, for the not supported files it shows a message that they are not supported, for the supported -> imports them without inserting frames for them.
   * ON_DROP_RESOURCE : It's event id is ImportEventIds.DND_IMPORT_RESOURCES, all the drag and drop logics fire such an event , the old logics will stay, because they are sorted in the right way, but they will only fire ecent for that handler... It uses the ResourceImportUtil to insert frames for resources. Drag and drop logic for resource from outside to Sophie is still not supported.
 
 * Exporting of resources... Different resources can be exported to different formats, some of the resources can be exported to more than one format. There should be an interface for exporting which extenders can be registered as extensions from the modules.
  * The export logic too will be in the fuc.resources module, in package called 'exports', to be consistent with the import logic.
  * There will be one interface for exporting of resources ResourceExportManager, and there will be an extension point in the func.resources module for it.
   * The manager will have method {{{boolean export(ResourceAccess access, File file)}}} which will export the given resource represented by the access into the passed file.
   * The manager will have {{{getResourceKind}}} method and {{{getFileFilter}}} method too, it will have {{{getExportFormat method which will give a description on the export of the resource.
   * The manager will be able to provide good example name of the file to save.
   * The {{{getResourceKind}}} of the interface will have special role, if the kind is just the {{{resourceR4.KIND}}} kind, it will mean that the export manager will be able to export any resource to it's format.
   * In the func.resources module there will be one implementation for SophieFormatExportManager. It will be able to export any resource to the Sophie 2.0 format:
    * Problem will be that the exported resources will not contain their outer references, but in the future, the persistence will support caching of resources in the format, so for now that works.
    * Other problem is that there are no sub revisions, so to persist the resources a new top access for them will be created by the their sub-model in the book.
  * ExportFormatDialog : One resource can be exported to one or more formats, so before exporting it the right format should be chosen by the user, this dialog will provide such choice.
  * ResourceExportLogic : This logic will handle resource exporting... for now there will be only one handler for events from the export button in the resource's tab. The logic will try to find all registered export managers of the selected to export resource and will bring up the ExportFormatDialog. Then a FileDialog with filter for the chosen format will be shown to the user. The user will be notified if the export was succesfull.
 * Filter buttons : They will be registered as extensions and the will have icons as a skin, the icons will be provided by Dido, I guess...

 * Our branch is [browser:/branches/private/meddle/resources_export_import]
 * Tests :
  * [browser:/branches/private/meddle/resources_export_import/modules/org.sophie2.main.func.resources/src/test/java/org/sophie2/main/func/resources/exports/ResourceExportManagerTest.java ResourceExportManagerTest]
  * [browser:/branches/private/meddle/resources_export_import/modules/org.sophie2.main.func.resources/src/test/java/org/sophie2/main/func/resources/exports/SophieFormatExportTest.java SophieFormatExportTest]
  * [browser:/branches/private/meddle/resources_export_import/modules/org.sophie2.main.func.resources/src/test/java/org/sophie2/main/func/resources/imports/ResourceImportUtilTest.java ResourceImportUtilTest]
  * [browser:/branches/private/meddle/resources_export_import/modules/org.sophie2.main.func.resources/src/test/java/org/sophie2/main/func/resources/imports/ResourceImportManagerTest.java ResourceImportManagerTest]
  * More with the implementation, there are use cases I want to check/test.
= Implementation =
 * Finished -> branch is [browser:/branches/private/meddle/resources_export_import] (svn://sophie2.org/sophie2/branches/private/meddle/resources_export_import)
 * The filter buttons/filters are added to the preview providers of every resource.
 * Script insert is in the edit menu now.
 * Added JPGExportManager and JavaScriptExportManager
 * A lot of bug fixes :)

= Testing =
^(Place the testing results here.)^

= Comments =
^(Write comments for this or later revisions here.)