[[BackLinksMenu]]

[[TicketQuery(summary=UNPLANNED_SCRIPTING_REFACTORING_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 =

== Overview ==
 * The goal of this task is to restore the previously working functionality of scripting in Sophie, replacing all obsolete code with new one, using the new model and views.
 * This is a refactoring task, so no new functionality will be implemented.

== Task requirements ==

 * Reimplement the following functionality, using the new model and views:
  * The user should have access to the current book and should be able to do the following actions with it:
   * get/set its title
   * get/set the page size (width and height)
   * get a list of all pages or a page with a given index
   * add a new page in it
   * remove a page
   * reorder the pages
   * get/set the current page
  * For every page the user should be able to:
   * get its name
   * get its index (but not set it)
   * get a list of all frames
   * add a new frame
   * remove a frame
  * For every frame the user should be able to:
   * get/set its size
   * get/set its z-order
   * get/set its content location
   * get/set its rotation angle
  * The user should be able to create a new book (which will be automatically added to the list of open books).

 * All model changes should be performed in {{{AutoAction}}}s.

 * Remove the deprecated code in {{{ScriptResourceH}}}.

 * Update the user documentation in [wiki:SCRIPTING_ACTIONS_API_R0#BasicUserDocumentation] if there are changes in the API.

 * Refactor all tests. 

== Task result ==
 * Source code
 * Updated wiki documentation

== Implementation idea ==
 * Currently {{{BookH}}}, {{{PageH}}} and {{{FrameH}}} are adapted for use in javascript. Instead, make the adapters to adapt {{{BookView}}}, {{{RootPageView}}} and {{{FrameView}}}, respectively.

== Related ==
 * [wiki:GROUP_SCRIPTING_R0]
 * [wiki:SCRIPTING_ACTIONS_API_R0]

== How to demo ==
 * Insert a new script in current book and run it.

= Design =

 * Common design ideas:
  * In all methods in {{{JS*}}} classes that modify the model execute a new insignificant {{{AutoAction}}}.

 * Rename {{{JSApp}}} to {{{JSAppMainWindow}}} and make it to extend {{{BaseJSAdapter<AppMainWindow>}}}.
  * Reimplement {{{jsFunction_newBook}}}:
   * Use {{{BookH.createEmptyBook}}} to create {{{ResourceAccess}}} to a new book. Use default settings from {{{BookInfo.DEFAULT_INFO}}}.
   * Create a new {{{BookDocView}}} for the newly created resource access object and add it to the documents list in the {{{AppMainWindow}}}.
   * Create a new {{{JSBook}}} using {{{Context.getCurrentContext().newObject}}}. Set its adapted object to the {{{BookView}}} in the newly created {{{BookDocView}}}.

 * {{{JSBook}}} should extend {{{BaseJSAdapter<BookView>}}}.
  * In {{{jsGet_title()}}} and {{{jsGet_pageSize()}}} just return the value of corresponding getter in {{{getAdaptedObject().getModel()}}}.
  * In {{{jsSet_title}}} and {{{jsSet_pageSize}}} set {{{BookR4.KEY_TITLE}}} and {{{BookR4.KEY_PAGE_SIZE}}}, respectively.
  * Refactor {{{jsGet_pages}}} to iterate over the immutable list from {{{BookH.getPages()}}}.
   * For each created {{{JSPage}}} set the adapted object to the {{{RootPageView}}} that corresponds to the page, using {{{BookView.getPageView(page reference)}}}.
  * {{{jsFunction_newPage}}} should create a new resource reference with {{{ResourceRefR4.generateRandomSub(PageH.NAME_PREFIX)}}}, then call {{{BookH.addNewPage}}} in the AutoAction, and finally create a new {{{JSPage}}}.
  * {{{jsFunction_removePage}}} should call {{{BookH.removePage}}}.
  * {{{jsFunction_movePage}}} should call {{{BookH.movePage}}}.
  * {{{jsFunction_setCurrentPage}}} should call {{{BookView.goToPage}}}.

 * {{{JSPage}}} should extend {{{BaseJSAdapter<RootPageView>}}}.
  * {{{jsGet_name}}} should call {{{PageH.getName}}}.
  * {{{jsGet_pageNumber}}}
   * find the parent {{{BookDocView}}}
   * get its {{{BookView}}}
   * get all pages in its model
   * iterate over it to find the reference to the adapted page
  * {{{jsGet_frames}}} - iterate over the list, returned from {{{getSubElements(FrameH.class)}}}. Use {{{AppViewUtil.getView}}} to find the frame view for each frame.
  * {{{jsFunction_newFrame}}}
   * create a new resource reference with {{{generateRandomSub}}}
   * get the list {{{CompositeElement.KEY_SUB_ELEMENTS.get(page.getAccess())}}}
   * call {{{FrameH.create}}}
   * create a new {{{JSFrame}}} and set its adapted object to the frame's view.
  * {{{jsFunction_removeFrame}}} - find the parent {{{ElementView}}} of the frame and remove it from the children list.

 * {{{JSFrame}}} should extend {{{BaseJSAdapter<FrameView>}}}.
  * {{{jsGet_name}}} - as in {{{JSPage}}}.
  * {{{jsGet_size}}} - call {{{getSize(BoundMode.OUT_BORDER)}}}.
  * {{{jsSet_size}}} - set the key {{{FrameR4.KEY_SIZE}}}.
  * {{{jsGet_zOrder}}} - get the parent {{{ElementView}}} and return the index of the frame in the list of children (which is a list of {{{ActivationChannel}}}s).
  * Replace {{{jsSet_zOrder}}} with the following void methods:
   * {{{jsFunction_bringToFront()}}}, {{{jsFunction_bringToBack()}}}, {{{jsFunction_moveUp()}}}. {{{jsFunction_moveDown()}}}.
   * make a private method {{{void setZOrder(int index)}}}. All of the above methods should call it.
  * {{{jsGet_contentLocation}}} - {{{getLocation(BoundMode.CONTENT, Position.TOP_LEFT, frameView.getTime())}}}
  * {{{jsSet_contentLocation}}} - {{{setRaw(MemberElement.KEY_LOCATION, channel.setChannelValue( <the time from the FrameView>, <the new point> )}}}
  * {{{jsGet_rotatingAngle}}}, {{{jsSet_rotatingAngle}}} - analogical to get/set the size.

  * Replace all hardcoded String literals, representing javascript class names, such as "Book", "Page", etc. with String constants.
   * For example, create a constant {{{public static final String CLASS_NAME = "App"}}} in {{{JSAppMainWindow}}} and replace all occurrences of "App" in the scripting module to {{{JSAppMainWindow.CLASS_NAME}}}.
   * Do the same for {{{JSBook}}}, {{{JSPage}}} and {{{JSFrame}}}.

 * In all {{{JS*}}} classes remove the {{{jsConstructor}}} method.
  * JavaScript users should not use the constructors. There are instance methods for creating books, pages and so on.

 * {{{RunScriptLogic}}}
  * ON_RUN_SCRIPT:
   * The script should not be executed in an {{{AutoChange}}}s.
    * All model changes are already wrapped in insignificant {{{AutoAction}}}s.
    * Execute new empty, but significant {{{AutoAction}}} after the script execution.

 * Update the user documentation with the minor changes in the API.

 * Source code:
  * [source:branches/private/mitex/refactoring-scripting-r0] - [6003], [6006]

= Implementation =
 * [6006], [6018], [6052], [6090], [6092]

 * In {{{ModelTestBase}}} the {{{MemLocator}}} was replaced by {{{AppLocator}}}. The same locator is used in the {{{AppMainWindow}}}, created in {{{AppTestBase}}}.

 * There was no need of {{{jsFunction_moveUp()}}}. {{{jsFunction_moveDown()}}}, because the user can write zOrder++ and zOrder--; therefore {{{jsSet_zOrder}}} was not removed.

 * {{{jsFunction_removeFrame}}} was not renamed to {{{jsFunction_removeElement}}}, because scripting does not support page elements other than frames. When this becomes possiible, {{{jsFunction_removeFrame}}} will just call {{{jsFunction_removeElement}}}. 

 * Merged in [6146]

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

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