Editing the application code

Where to look for the application files?

Once you create your own application, it is stored in a repository within the Application Workbench. All your repositories (applications) are listed at the start page of Application Workbench when you log in (if you do not have the Application Workbench account yet, please consult this guide). A sample view is shown on Figure 1 - the right panel contains a list of repositories containing your applications or applications shared with you by other users - one of such repositories is marked in the figure. The first part (here: tcs-test-user) of the repository name is the username (yours or the user who shared the repository with you), the second part (here: TestApp) is the application name. The central panel of the page is a list of activities related to these applications - e.g. the latest modifications.

Figure 1. View of the Application Workbench start page, with repository containing TestApp application marked

If you are in the EPISODES Platform, you can access directly the code of one of your applications from the My Apps page, by choosing the Code repository link (see Figure 2). This is equivalent to following the repository link from Figure 1.

Figure 2. View of the My Apps page within the EPISODES Platform.

Editing files through Application Workbench Web interface

The Application Workbench provides you with a Web interface allowing for simple file edition and controlling the modification history. Though the interface provide content assistance and other features that facilitate programming, it is still a simple text editor, therefore, if your application requires advanced programming constructions or uses many files, it is recommended to edit its files on your computer and publish the changes to the repository from there (this mode of edition is described in Editing files from your own computer section). In this way, you will be able to use your favorite IDE (Integrated Development Environment), e.g., MATLAB Workbench and to publish changes to multiple files at once. Naturally, the same effect can be reached using the Web interface, however, it might be less comfortable in the aforementioned cases.

Contents of the application's repository

Once you enter the repository containing your application, a page containing its main directory will be displayed (Figure 3). If you used the EPISODE Platform's wizard for creating the application, the repository will be already populated with files automatically generated by the Platform - the files are represented by rows in the central part of the page, with the file name on the left (marked with (1) in Figure 3) and the comment explaining the last modification and date of this modification displayed on the right (marked with (2) in Figure 3). Note, that if you created the application repository manually, the repository will be empty or it will contain only a README.md or license file (depending on your chosen settings), but it will not contain the configuration and execution files required by the EPISODES Platform to use the application - you will have to add them manually. Adding a file is possible using the New file or Upload file button (marked with (3) in Figure 3). Choosing the New file button will result in the system showing an edit page (as in case of editing a file - see Figure 5 and further paragraphs). Note, that it is not possible to create a directory in this way, a directory can be created only implicitly by editing a file name (see the next subsection) or by creating a nested directory structure on your computer and publishing it to the repository (see Editing files from your own computer section).

To access the application's repository settings (e.g. add collaborators, that will be able to see/edit your application), use the Settings button (marked with (4) in Figure 3).

Figure 3. Main view of the repository containing the TestApp files, with most important elements marked

When entering any of the files (by clicking the file name - (1) in Figure 3), a view similar to Figure 4 is displayed, showing the file contents and controls. In case of entering a directory, the contents of the directory (files) are displayed similarly to the file listing shown in Figure 3. The pencil icon (marked with (1) in Figure 4) enables editing the file (see Figure 5), the trash icon (marked with (2) in Figure 4) allows for deleting the file, and the button History (marked with (3) in Figure 4) shows the history of modifications of the file.

Figure 4. View of chosen file contents, with most important elements marked. Here: the file app_script.m from the TestApp application

It is also possible to view a raw version (without any additional options and line numbering), by using the Raw button (Figure 4). The file can then be downloaded by using the Web browser's option Save as... (CTRL + S). Creating a permanent link to the file view can be achieved with the button Permalink. Note, that this will create a link to the exact version of the file you are viewing at the moment.

Editing files and saving changes

Once in the editing mode, the text editor allows for any modifications to the chosen file. Continuing with the example displayed from the previous section (Figure 4), we changed the contents of the app_script.m file adding the body of the function app_function. This is done in the text editor - marked with (1) in Figure 5. The changes can be checked within the Preview Changes tab (marked with (2) in Figure 5) - with an effect as shown in Figure 6 - the changed lines are marked with colors. To change the name of the edited file, use the field marked with (3) in Figure 5 (the current file name is already inserted there). In this way, you can also create a directory to put the file in - by inserting a directory name, followed by the / (slash) path separator before the file name. E.g., to put the app_script.m in a directory dir, we would need to change the content of this field to dir/app_script.m. Note, that it is not possible to create an empty directory in this way.

Saving the changes both to the file name and its contents is realized with the Commit Changes button (marked with (5) in Figure 5). This operation is TODO

. It is also advisable to add a comment with the change (field marked with (4) in Figure 5), describing it and, possibly, its purpose. If no comment is provided, a default "Update '<filename>'" (here it would be "Update 'app_script.m'") is inserted by the system. The comment related to the latest version of a file is later visible in the directory listing view (see marking (2) in Figure 3).

TODO

(for those already familiar with the GIT versioning system, this committing in fact performs both git commit and git push)

Note, that, apart from the text editor, the other controls of the Preview Changes tab are the same as in the Edit File tab, therefore, you can perform all the operations except for the file contents editing on any of the two tabs.

Figure 5. Edition view of the app_script.m file, with text editor and other most important elements marked

Figure 6. Edition view of the app_script.m file, with change preview

Editing files from your own computer

This mode is especially recommended when editing multiple files at once, or creating a nested directory structure inside the application.

TODO: edycja na własnym komputerze z użyciem poleceń Git-a (najlepiej link do jakiegoś podręcznika git-a, lub ew. tylko podstawowe polecenia, IDE)

TODO: edycja musi być skorelowana z edycją appDefinition.json

Even when editing files locally, it is advisable to check the effect of the changes in the Application Workbench Web interface (see the previous section), and, even complement the local modifications with small edits performed through that interface.