File+Operations

This documents the functionality that we are adding to mathies apps gradually. Not all file operations are available to all tools.

How the operations are performed depends on whether you are using the tool:
 * 1) in a Browser (Chrome, Firefox, Safari, Edge etc.)
 * 2) as an installed desktop Application (Windows or Mac)
 * 3) as an App on a mobile device (iOS or Android)

Files saved by mathies tools are actually in the XML format. They use a custom extension (like .relrods) so that they can be associated with the correct application. If you install Relational Rods as an application on a Windows or Mac computer, you can double-click a .relrods file and have Relational Rods open and load that file.
 * File Types**

You can also save the files with either the .xml or .txt extension and be able to open them with the tool later on. The xml and txt file types are useful if you want to open the file in another application, like a text editor, or if you are putting the files on a web server. 
 * Operations:**
 * 1) Save
 * 2) Open
 * 3) Open from Web
 * 4) Import
 * 5) Import from Web
 * 6) Window Size Warning
 * 7) Using Google Drive
 * 8) Transfering Files from a Mobile Device to a Computer
 * 9) Advanced

 Save The Save File operation is accessed using the Save Button in the Settings dialog or by using the keyboard shortcut SPACE+S.

The saved file will include: Note: Imported images will not be saved.
 * all tool specific objects
 * the undo/redo history steps, when available
 * the final state of any annotation.

**Browser or installed desktop Application** Pressing this button will bring up the system dialog with a suggested file name and file type (e.g., .coltiles for the Colour Tiles Tool). It is recommended that you do not change the file type since the //Open// operation gives preference to files with that extension (or with .txt and .xml). The suggested file name is based on the date and time of saving and should be unique.

NOTE: Some browsers, like Edge, might strip the extension from your file if you change the file name from the default. Opening from the same browser should still show your file, but other browsers, like Chrome, may not recognize those files unless you click on the drop down menu beside the search field and make sure "All Files" is selected. NOTE: On a Mac, some browsers, like Chrome or Opera, use the Custom Files filter by default in the Open Files dialog. To switch to All Files, click on the "Options" button found in the bottom left corner of the dialog box.

Android App or iOS App (iPad/iPhone)
Apps use a dedicated Documents directory. Files will be saved by default to the mathies subfolder of that directory. The suggested file name is displayed in the input text box at the bottom of the dialog. It is based on the date and time of saving and should be unique. You can also click on a file to copy its name to the input box. You can, of course, also edit the textbox to supply your own name. It is recommended that you do not change the file type (e.g., .relrods for Relational Rods +) since the //Open// operation gives preference to the expected extension (and .txt and .xml). Double-click on a folder to browse its contents. Press the Save Icon to save the file with the file name displayed. If you supply a valid name it will be used.



If the file already exists, you will be presented with a Warning Dialog, which allows you to continue the save operation or cancel it.



Press "+" to add a subfolder.

Press "^" at the top left of the dialog, when available, to navigate up to the parent folder.



Saving in a Tool with Undo/Redo
Typically, you would think to press Save at the end of a bunch of work. However, students are often encouraged to save a file so that they can review the entire sequence of their work with an educator or peer.

If a file is saved at the end of the steps, it can be opened, undo can be pressed until it is at the beginning of the steps and redo can be pressed to review each step. Alternatively, undo can be pressed to get to the beginning prior to saving. Then when the file is opened, redo can be pressed right away to move through the steps from start to finish.

In fact, you can save the file at any point in the undo/redo sequence. When a file is opened, it is restored to the step at which it was saved. The undo/redo buttons are active and work just as they would have in the original workspace.

Example
The first supplied example for the Set Tool (mathies.ca/files/examples/ST_Ex1.xml), saved at the beginning of the work, is supplied as an alternate example below. When the file is opened, there is nothing on the workspace (other than the annotation), the undo button is inactive, but the redo button can be used to review all the steps from the beginning.

Notice that when you open the file, all the annotation appears on the screen. This is because only the final state of the annotation is saved and loaded and currently there is no undo/redo for annotation.
 * === **Image** === || === **Example** === || === **URL** === ||
 * || (click on the link on Desktop) || (type or copy into Open WWW text box, or right-click and save locally) ||
 * [[image:Set_Ex1_FromStart.PNG width="480" height="297"]] || Set Example 1 Saved at the Start || @https://mathies.ca/files/examples/ST_Ex1_FromStart.xml ||

top  =Open= The Open File operation is accessed using the Open File Button in Settings, using the keyboard shortcut SPACE+O, and from an icon on some tool's opening screens.

The open operation allows you to open a file which is saved on the device you are working on.

When you open a mathies file into the **same** mathies tool where it was created you will :
 * see all of the tool specific objects
 * see any annotation that was saved.
 * be able to press undo/redo to see the steps that were used to create the file, when available

When you open a mathies file into a **different** mathies tool than where it was created you will see only the annotation that was saved.

In either case, you will be able to manipulate the objects in any way you like and continue working in the tool.

Opening a file resets the tool prior to loading the file. If you have done any work with the tool prior to opening a file, a warning dialog appears as a reminder of this fact. Press //Open// to proceed or //Cancel// to go back to save any work that matters.

**Browser or installed desktop Application** The system dialog appears which allows you to find the folder in which you have saved the files of the required type (here, relrods).



Use the file type dropdown to search for .xml or .txt files. On some systems, you will change the dropDown to All Files, or click an Option button, to see files that do not have the custom file extension.

**Installed desktop Application** There are two other ways to open a file for an installed mathies tool:
 * 1) Double-click a file of the related type
 * 2) Drag a file of the correct type onto the tool's window

Android App or iOS App (iPad/iPhone)
On mobile devices, a custom dialog appears which displays the files and folders available. The name of the current directory is displayed in bold face at the top. Click on a file to open it in the tool. Double-click on a folder to open it for viewing. Use the scroll bar to view more files and folders. Press "^" at the top left of the dialog, when available, to navigate up to the parent folder.



Apple has gone to a lot of effort to have their devices not act like other storage devices. However, each app does have some storage for its documents. The custom dialog will display the files available in the mathies subfolder of this directory. These files are at risk of being deleted when a new version of the app is installed (they should be fine if the app is updated). See the section below for information about how to transfer files from a device to a computer for safekeeping and distribution. Note: Saving files in a subfolder may make them harder to transfer using iTunes.

top  =Open from Web= The Open File from Web operation is accessed using the www Button in Settings or using the keyboard shortcut SPACE+SHIFT+O

Open from Web allows you to open a file from a URL as opposed to from your device. Otherwise, the functionality behaves the same as for open.

You will be prompted for a valid web address. Press OK once you have entered the address completely. Like many other mathies dialog boxes, you can press ENTER instead of clicking OK (this works on a mobile soft keyboard as well).

Each tool includes two sample files (Ex1 and Ex2) which highlight various aspects of the tool. Wiki pages for each tool contain a sample files section which includes other saved file examples. ( e.g. Notepad Sample Files)

In order for this //Open from Web// operation to be successful,
 * 1) "//http:"// must be used in the address
 * 2) the file must be on the server
 * 3) the filetype must be supported on the server - .txt and .xml are pretty good bets, the mathies specific extensions less so
 * 4) the file must be in a valid format created by the mathies tool
 * 5) OK must be pressed


 * If you are using a browser and if the tool and the file are on different servers, you often will get security errors using this method. If so, you should download the file to a local drive to open it.**

//Advanced:// //Web pages generally know how to serve up .xml files. The XML files used by mathies tools have custom extensions, like .moneytool and .relrods.// //The server admin would need to set up MIME types for these custom extensions in order for the loading to work.// //You can use a text editor to view these saved files, if they are not compressed, and tweak them if you are brave.//

top  =Import= The Import File operation is accessed using the Import File Button in Settings or using the keyboard shortcut SPACE+I.

Importing a mathies file results in the content of the imported file being added to the stage alongside any content that is already in place. Consider saving your work before importing for safekeeping. If the existing work and the imported file contain objects at different sizes every attempt is made to maintain the current state of the tool which means that imported objects may be adjusted to fit. The import operation includes only the final state of tool specific objects and annotation. Pressing undo removes all the imported tool objects in one step. At this time, it is not possible to distinguish imported annotation from annotation created prior to import so the user will have to remove any unwanted annotation objects themselves.

The import operation steps are the same as for the Open operation described above. top  =Import from Web= The Import from Web File operation is accessed using the www Import Button in Settings or using the keyboard shortcut SPACE+SHIFT+I.

This operation allows you to import files from a specified URL as described above. Consider saving your work before importing for safekeeping.

top  =Window Size Warning= Sometimes a file might have been saved in one window size and you are trying to open or import it in a smaller window size. A warning message appears when this happens and red arrows appear to indicate which dimensions are awry.

If you press Load prior to adjusting the window, then objects will be scaled to fit the smaller window as best they can. Annotation and objects might not align properly. In extreme cases, some items may be off the stage.

If you choose to resize your window until the arrows turn green, then everything should load just fine.



On mobile devices, a message might appear suggesting that you rotate the device prior to loading. Since some mathies tools are locked into a landscape orientation, this will not always be possible.



Helpful Hint
When opening a file what was saved on a different device or at a different screen size, you may get better results if you increase or decrease the size of the tool's objects after loading the file, using the sizing arrows or the settings.

top  =Google Drive= mathies files can be saved and loaded with Google Drive.

The video below describes the process using a Chromebook, although the procedure is similar on a Windows and Mac computer with Drive installed (see @https://www.google.ca/drive/download/).

Click the image below to play the video.



top  =Transfering Files from a Mobile Device to a Computer= **Android App** Depending on the security settings on your device, you may be able to connect your device to a computer and transfer files back and forth. Check for documentation related to connecting your device in a file transfer friendly mode.

Files App (iOS 11+)
The video below explains how to use the Files App to transfer files between a mathies app's folder and other locations, such as iCloud Drive, Google Drive, OneDrive and Dropbox. media type="custom" key="29652325"

iTunes File Sharing
This method requires a computer connected to your iOS device.

Some mathies apps have File Sharing enabled, and so you can: > > > > > >
 * 1) Connect your device. Open iTunes if it doesn't happen automatically.
 * 2) Click on the image of the device - the fourth button at the top left.
 * 1) Click on File Sharing at the bottom of the list at the left.
 * 1) Use the //Add File// and //Save to// buttons at the bottom right to transfer files.



For more information on File Sharing, see the Apple Support page

top  =Creating a link that will open the tool with a file (Advanced)= You can provide a web link to open a mathies tool in a browser with a particular file loaded using the openFilePath parameter. Take note of the web address that you are taken to from mathies when you open a tool. It will be something like: The information after the .html are parameters used to give information to the webpage about which tool to load, what the page title should be and what language should be used.
 * @http://mathclips.ca/swfPlayer.html?swfURL=tools/RelationalRods1.swf&title=Relational%20Rods+&language=fr**

In order to specify, a file to open, add something like to the end of the address to get:
 * ``&openFilePath=https://mathies.ca/files/examples/double5elbows.relrods``**


 * @http://mathclips.ca/swfPlayer.html?swfURL=tools/RelationalRods1.swf&title=Relational&20Rods&openFilePath=https://mathies.ca/files/examples/double5elbows.relrods**

If this doesn't work, then there has been some sort of security error communicating between the web servers - generally the server with swfPlayer.html and the server with the file have to be the same or have the necessary crossdomain privileges. In addition, you might find that renaming the file with a .xml or .txt extension will work better.

top