page-template-apply-dialog -- Create a dialog for applying templates

[deyan]

Template apply dialog allows the user to assign frames to slots from the template when applying the template. See Templates

• Each of the existing frames can be
  • assigned to a slot (1)
  • left unassigned to a slot(2)
  • deleted (3)
• For each slot
  • a new frame can be created (4)
  • can be assigned to an existing frame (1)
  • can be unused (5)

Behavior:

(1) The frame is assigned to this slot. Slot options that were checked on template creating are applied to the frame. If the slot is modified, changes are applied to the asociated frame(or frames on more pages). If the slot is deleted, the frames associated to it on different pages are removed.
(2) The frame remains on the page untouched. Z-order is undefined, but the behavior is not important. Changing template (and slots) does not affect this frame. ^*
(3) The frame will be deleted^*
(4) New frame is created and associated with the corresponding slot. Unchecked checkboxes fallback to the parent template (or the empty)
(5) The slot is unused for this instance. Changing (or deleting) this slot does nothing to the instance.

^* Due to difficult user interface, this could be chosen for all of the existing frames on the page.

• Default behavior: By default, "New" should be selected for all of the elements in the template
• Groups: For new groups, only "New" and "None" should be available. For existing groups, their elements should be available as options.

[todor]

very good analysis, it contains all the things that are needed for this task and were discussed

[deni]

• As we agreed, for now nothing will happen if a slot is deleted from a template or a new slot is added. This might be changed in another ticket.

[deni]

• Create a new class Slot in org.sophie2.main.func.templates.page package.
  • A slot represents the association between a template element (group or frame) and its target. The target might be an existing element to which the template should be applied, the indication that a new element should be created by the template or the indication that the template should not be used at all.
  • Slot extends BaseProObject
  • Most important members:
    • Prop<Slot> parent() - parent property.
    • Prop<ElementH> template() - a final property holding the template the slot is responsible for.
    • RwProp<Target> target() - a read-write property holding the current target for the template. This property will be set by the logic for the 'Apply page template' dialog.
    • ListProp<Slot> subSlots() - a list of slots for the sub-elements of the slot's template. Owns them.
  • Target - inner static class for Slot. Objects from this class determine what to do with a template.
    • Target has a private constructor by ElementH (existing element to which to apply the template) and String (name).
    • Target can be instantiated by create methods which assert that the given element is not null.
    • There are 2 special Targets - NEW_TARGET and NONE_TARGET.
      • NEW_TARGET determines that a new element should be created by the template and NONE_TARGET - the template should not be used at all.
      • Their target resource is null.
      • They are constants in the Target class.

• Create a new class ApplyTemplateInfo in org.sophie2.main.func.templates.page package.
  • It will hold the settings for applying a page template and will be used as a result from the 'Apply page template' dialog. It will use Slots to determine what to do with the groups and frames from the template.
  • Important members:
    • Constructor by 2 ElementHs - the template and the page to which it should be applied. All neccessary slots will be created here.
    • public ElementH getTarget() - gets the page to which the template should be applied.
    • public List<Slot> getSlots() - gets the list of top-level slots. These are the slots for the immediate sub-elements of the page.
    • public boolean shouldDeleteOther() - checks whether after applying the template, the existing elements that were unassigned to slots should be deleted.

• Create a new class for the dialog displayed when applying a page template - ApplyPageTemplateDialog.
  • extends Dialog<ApplyPageTemplateDialog.Input, ApplyTemplateInfo>
  • ApplyPageTemplateDialog.Input - just creates the inital ApplyTemplateInfo using the template and the page to which it should be applied.
  • ApplyPageTemplateSwingDialog - the actual swing representation of the dialog, will be described below.
  • protected ApplyTemplateInfo show(Input input) - shows a ApplyPageTemplateSwingDialog and returns the information it has gathered.

• ApplyPageTemplateSwingDialog
  • extends BaseCustomModalDialog
  • ListProp<SwingVisualElement> controls() gathers the controls to show in the dialog and Prop<JPanel> contentPane() adds them to a JPanel.
  • public static class DeleteOtherCheckBox extends BoundCheckBox - a checkbox to choose whether the existing elements that were left unassigned should be deleted.
  • public static class TargetComboBox extends BoundComboBox<Target> - a combobox used to choose the target of a given slot. Just an inner class and not a child of ApplyPageTemplateSwingDialog. Will be instantiated directly.
    • Constructor by Slot
    • Implements ComboState<Target> computeModelData() in the following way:
      • The available options are computed depending on the parent slot's target. This logic is described in the analysis.
      • The selected item can be retrieved from the slot (its target). However, it might not be present in the available options. This means that it is obsolete and should be updated (for example with 'NEW').
  • public static class SlotsPanel extends BaseSwingVisualElement - a panel with controls for associating the groups and frames from the template to their targets.
    • private ListProp<JLabel> titleLabels() - contains the titles for the slots.
    • private ListProp<TargetComboBox> targetComboBoxes() - contains comboboxes for choosing targets for the sub-templates, in the same order as the titles. Owned by SlotsPanel.
    • public Prop<? extends JComponent> swingComponent() - a ResourceProperty containing a panel, which on the other hand contains two other panels - one for the titles and one for the comboboxes.
      • I think that it would be better without the above two properties, the labels and comboboxes could be created here, but in this way the TargetComboBox-es would not be children of the dialog. This causes some problems...

• Changes in ApplyPageTemplateHandler:
  • On dropping a template over page, show the ApplyPageTemplateDialog and extract its ApplyTemplateInfo.
  • The info should be transformed to a list containing the elements to create and a map from templates to existing frames. This will be done in private methods, recursively procissing the slots from the info.
  • Then, TemplateUtil.applyPageTemplate(PageH, ResourceRefR4, Map<ResourceRefR4, ResourceRefR4>, List<ElementH>) should be called.

• Changes to TemplateUtil.applyPageTemplate(PageH, ResourceRefR4, Map<ResourceRefR4, ResourceRefR4>, List<ElementH>):
  • iterate through the map entries and apply frame templates to existing frames.

[pap]

• I like most of the design, the way it is presented and that most of the JavaDoc is nice.
• Following are the remarks that you should consider.
• I think that the "Delete existing objects on the page" should be named "Delete unassigned elements". Or I don't understand its idea correctly.
• About deleting we could have something as a trash slot.. but I cannot think of a full idea right now. You might give something similar a try.
• I suggest making a new package - "composite" or similar as the presented logic is not specific to pages. And the latter fact is quite nice :)
• In the Slot class instead of setting the target property in the constructor it is much better and clearer to give a default value in the makeProp method ;).
• Why does the Target class have hashCode and equals methods? It is not immutable so you might consider two targets equal and then they can change while you think they are still equal.
  • I suppose you use too much ElementHs. For example I don't get why the Target class needs it. Also why does it have a name in it?
  • If it is becuse of what is displayed in the combo boxes their content for "none" and "new" should be skinnable anyway.
  • You might have a look at LinksHud.EMPTY_RULE its usage and skinnig and if use it if you like it. Or you may use a different solution.
  • You might just use a ResourceRefR4 as target and have several inner classes for the special cases, or you may dislike this idea :)
• Don't create VisualElements that way (using constructors). Use the providers and their create method. Visual elements must have a default constructor.
• I think that the template may change while you are displaying the dialog. If you have a server book and it is opened by two clients. The page template may get overwritten while being applied.
• This would lead to at least recomputing all labels. So you may make a SwingVisualElement wrapping the label that has the slot as its model and just changes the title of the label.
• Also it is better to split the components a bit more. It is not nice to recreate the titlesPanel and comboBoxesPanel every time.

[deni]

• The implementation is done according to the design with some changes described below.

• Refactored TemplateUtil.applyPageTemplate(PageH, ResourceRefR4, Map<ResourceRefR4, ResourceRefR4>, List<ElementH>) to traverse the subelements tree of the page template (using BFS) and for each node do one of the following:
  • apply it as a template to an existing element from the page
  • create a new element on the page
  • nothing
    

Simply iterating through the list of sub-templates from which new elements should be created is not working because we don't know which element should be parent of the new one.

• In ApplyPageTemplateHandler after parsing the template info deleted the elements that were left unassigned to slots. It is important to do this before adding any new elements in TemplateUtil.applyPageTemplate, because otherwise they will be deleted, too.

• Made ApplyTemplateInfo a BaseProObject so that checking/unchecking the 'Delete unassigned elements' checkbox does not cause the slots panel to update.

• Added a ListProp<ResourceH> in SlotsPanel holding the page elements that are currently assigned to slots. ON_TARGET_SUBMIT operation makes sure to update this property and the model of TargetComboboxes does not include elements from this list. Thus the user cannot assign one frame to two slots (the behavior for this is not defined).

• Added a WindowAdapter to the JDialog in BaseCustomModalDialog to ensure that the dialog's close button has the same behavior as the 'Cancel' button and the Esc key. Otherwise the dialogCanceled() is not called, the applyTemplateInfo() property in the ApplyPageTemplateDialog is not set to null and the logic for applying templates treats this as 'Ok'.

[deni]

• Since applying templates is a slow operation, the 'Sophie is working' label should be shown. However, currently no EventR3 is fired for drop in a DnD operation and this will not happen.
  • The existing (but currently not used) DndImport class should be changed to keep the responsible DropHandler in a private field.
  • A new event should be added to TransferEventIds - DND_IMPORT fired when a transferable is dropped over a component. It will have a single parameter - the responsible drop handler,
  • SophieDragDropHandler.drop(DropTargetDropEvent) should be changed to fire DND_IMPORT instead of calling DropHandler.handleDrop(...).
  • A new logic with a single operation ON_DND_IMPORT should be added. The only thing it should do is call DropHandler.handleDrop(...).
  • I'll update the patch with the implamentation to include the above changes.

[pap]

• Commited in [9050]
• Using several AutoActions.... - TemplateUtil, BookView
• In TemplateUtil instanceof GroupElementR4 instead of CompositeElement.
• Also in the same place using fixed kinds for frame and group isn't nice. Use the kind that ElementH provides.
• Indent in constant in label adding
• You can check for the provider before starting the creation of the labels/boxes - will save iterations.
• Sizes of Rigid areas in mainPanel should be constants
• Combbox and panel could also be registered with the @RelatedChildren annotation.
• Use interfaces instead of classes where possible (List instead of ArrayList)

[meddle]

Closing all the tickets before M Y1