OMGUI - Frontend

This repository holds the GUI frontend code for the OMGUI library.

The OMGUI frontend is written in Vue.js with Vite as build tool, using the composition API with TypeScript and SCSS. The molecule viewer relies on RDKit for 2D visualization and Miew for rendering interactive 3D molecules. It's based on the Carbon Design System.

Running Development Server

To run the frontend development server, you first need to launch the OMGUI server.

pip install omgui

import omgui

omgui.launch()

Now launch the development server in a separate terminal.

npm run dev

Build Process

OMGUI supports a custom base path. To pull this off, the frontend build is exported with a hardcoded __BASE_PATH__ which is replaced on the fly by the server. The base path is set in index-build.html as a <base> tag, which takes care of native browser URLS, and in vite.config.ts from where it's loaded into the Vue router, taking care of all Vue-managed links.

To build locally:

npm run build

Publishing New Version

1. Publish a new release on GitHub, respecting semantic versioning
2. The release-build.yaml action will run the build script and store the build files as dist.tar.gz alongside the source code of your release. It will take 1-2 minutes to appear, you can follow the process under the Actions tab.
3. In the OMGUI repo, update the OMGUI_FRONTEND_VERSION environment variable to the new version number (exluding the 'v' prefix) in both your .env and the .env-example file.
4. OMGUI will automatically download the frontend code on the first launch, and will update it whenever a new version number has been detected. The installation process extracts the contents of dist.tar.gz and stored them under /omgui/gui/client.

How things work

File Browser

• OMGUI - File and directory information & content is read by _compile_filedir_obj() and compiled into a data object representing the file or directory.
• The data object will look something like this:

{
	"_meta": {
		"errCode": null,
		"ext": "txt",
		"ext2": null,
		"fileType": "text",
		"size": 120,
		"timeCreated": 1724857839569.6558,
		"timeEdited": 1724856402224.3848
	},
	"data": "hello, world",
	"filename": "example.txt",
	"path": "foobar/example.txt",
	"pathAbsolute": "/Users/johndoe/.omgui/workspaces/DEFAULT/foobar/example.txt"
}

• Depending on the file type, the data attribute will contain a string (for text-based files) or an object (for structured data files).
• Different file types (as defined by the file extension) will open in different file viewers. In ViewerDispatch.vue the correct viewer is loaded by loadModule() and then the file data is transferred into the appropriate viewer store by parseRoute(). To see how file extensions are mapped to the appropriate file viewer, see below.
  • Molecule viewer: For displaying .smol.json files, which contain an OMGUI-native molecule object. Industry-standard molecules file formats like .pdb and .mol are translated on-the-fly and will also open in the molecule viewer.
  • Molecule set viewer: For displaying molset.json files, which contain a list of OMGUI-native molecule objects. Industry-standard molecule set files like .sdf or .smi are translated on-the-fly and will also open in the molecule set viewer.
  • Data viewer: For .csv files and Jupyter dataframes.
  • Text viewer: For text-based files like .txt, .md and .yml
  • JSON viewer: For .json files
  • All other files (eg. .pdf) will be opened by the native application of your operating system (eg. Preview on macOS).
• OMGUI - On-the-fly translation of file formats happens bt _attach_file_data().
• The file object and its data is then consumed by loadItem() in the FileStore.

Developer Tips

Adding support for new file types:

• OMGUI - Add the file extension to _get_file_type().
• Add the display name and correct viewer to _map_FileType in src/utils/maps.ts

Adding support for new molecules file types:

• Update parseRoute() in ViewerDispatch.vue to ensure the filetype results into the correct loading of data into the store.
• Update setMolData() in MolViewerStore.ts if needed.
• Update actionSaveAs() in OverflowMenuMol.vue to ensure the correct options are displayed in the overflow menu, and ensure the delete option is also included.