[[BackLinksMenu]]

[[TicketQuery(summary=SCRIPTING_ACTIONS_API_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 expose the Sophie book's model and Sophie's logic in a user-friendly way to the user.

Generally, there are two use-cases for scripting, which imply some differences in the requirements:
 * Scripts used for automation
  * The result of their execution should be undoable, as each other change to the model
 * Scripts as link targets
  * They have limited scope - for example, user cannot create a new book with them
  * There's no need to be undoable

== Task requirements ==

 * 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/set its name
  * get its index (but not set it)
  * get the bounding rectangle (a rectangle that contains all page elements)
  * [Optional for this revision] get/set the background style
  * [Optional for this revision] get/set the border style
  * 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
  * get/set its background style
  * get/set its border style
  * get/set its paddings
 * [Optional] The user should also be able to work with groups.

 * Allow scripts to be defined as link actions.
  * The action settings panel should contain a combo box with all available scripts for current book.

 * Not all Java classes have to be exposed to Sophie scripts, because:
  * Some scripts can crash the application.
  * Some other scripts can allow crackers to execute malicious code.

 * When closing a book, close any open document windows that display scripts for current book. Generally, when closing a document window, close all children's document windows.

== Task result ==
 * Source code

== Implementation idea ==
 * Decide whether to expose the model classes (org.sophie2.base.model.book.Book, org.sophie2.base.model.book.Page, org.sophie2.base.model.book.Frame, etc.) or to write facade classes.
  * The first approach will make scripts very powerful - the user will be able to do with them everything he/she can do with the application. In addition, it won't be necessary to update the facade every time we change something.
  * The second approach however will be more convenient for the user. It will also solve most of the security issues.

 * To filter the access to some Java classes:
{{{
context.setClassShutter(new ClassShutter() {
	@Override
	public boolean visibleToScripts(String fullClassName) {
		return fullClassName.startsWith("org.mozilla.javascript");
	}
});
}}}

 * The following lines add a global variable {{{out}}} that is a JavaScript reflection of the {{{System.out}}} variable:
{{{
Object wrappedOut = Context.javaToJS(System.out, scope);
ScriptableObject.putProperty(scope, "out", wrappedOut);
}}}

== Related ==
^(Add links to related tasks that could be useful or helpful.)^

== How to demo ==
^(Provide instructions for demonstration of the task.)^

= Design =
^(Describe your design here.)^

= Implementation =
^(Describe and link the implementation results here (from the wiki or the repository).)^

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

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