Currently Projects are defined by a single JSON file and though JSON is an excellent format for machine driven I/O, it can be cumbersome for project designers to define new types of projects and workflows. In addition, the current format does not tend to encourage reuse of project building blocks such as Views, Styles, Worklets and Type definitions.
What Its being proposed is to define a project template specification that is similar to an Attribute’s SBT file that is more human readable, can be broken down into reusable sections and that can be used to generate projects. The targeted format being considered is XML.
Sections of Project Template
Project Core Information (Required)
This section contains information about the project itself and includes the following:
- Project Type Name - what is the type of project being defined (this can also be considered as the schema type of the resulting project)
- Template/Schema Version - This could be used when updating an existing project to a newer version of the template
- Project Description
- Resource Subsection that defines the resources that need to be created by the project.
- In the case of attribute resources, this would also contain the relative paths to the relevant SBT files or refer to the entries in the Attribute Resource Section. In theory you could also include the Attribute Resource’s XML within an element in this section.
- For geometry, this could be a file path to the file that needs to be loaded in (either a smtk representation and/or native geometry such as exodus, OpenCascade, or STL.
- Is the project derived from another project template? (Future expansion for Project Templates) In the immediate future this would be mainly used to indicate that all of the parts of the base project should be included in this one with the exception of the Project Core Section.
Include Section (Optional)
This would have a list of files to be included that the project template will also load into memory. This would allow section reuse between project templates. All of the following sections could be distributed into a set of include files. Each of these files would follow the same XML structure.
In addition, this section would include an include search path element that would list the places to search for include files in addition to the location of the project’s template file.
Plugin Section (Optional)
This section would provide a list of plugins (including their locations relative to the project template file) that need to be loaded when a project is generated from the template. In addition, this section would include an include search path element that would list the places to search for plugin files in addition to the location of the project’s template file.
Task Management Section (Optional)
This section would define workflows, tasks, worklets, ports, connections, etc… used by the project and would contain the following sub-sections. Note that it should be possible to include files to encourage reuse of the various sub-sections.
Worklet Section (Optional)
This section would define the worklets that the project workflow can make use of.
Workflow Section (Optional)
This section would define the project’s workflow - it could also refer to a JSON file that defines the workflow.
Task Definition Section (Optional)
This section would define the structure for a Task that can either be referenced in the workflow section or could be instantiated during workflow editing in the application.
View Configuration Section (Optional)
This would also include attribute views for the attribute editor panel as well as those for the panels such as the diagram, operation and 3D view panels.
Default Panel Styles Section (Optional)
This would specify what should be displayed in various panels by default when there is no active task or if the active task does not provide its own styles. It may specify the panel configuration (which dock area the panel appears in and, if tabbed, the order within the tabbed panels) as well as default panel visibility.
Attribute Resource Section (Optional)
This section would contain a list of attribute sbt files (each referred by a reference label).
Operation Section (Optional)
This would allow the project to filter and relabel core SMTK operations as well as pointing to files containing Python operations. In addition, it would also identify the operations required to create and read in projects of this type.
Lifecycle of Projects and Their Templates
Template Creation
Workflow developers may manually create an XML document.
Users may “Export” an existing JSON project as an XML project template.
Template Installation
The location of the template XML is what determines its availability as a project template. SMTK should provide locations that are searched for project templates:
- a “system” directory related to the location of the smtkCore library on the filesystem (…/share/smtk/project-templates/)
- a per-user directory (~/.config/smtk/project-templates)
- failing that, a set of optional site-specific URLs (https://computationalmodelbuilder.org/project-templates/ or perhaps others specific to an organization)
Project Creation
Users create projects by choosing a template from the gallery. A reference to the template file is stored in the project (in core).
Project Save
When a project is written to disk, there should be either a reference to or a copy of the template XML included in its saved location. Each option has its unique set of issues:
- If stored as a reference
- Then projects may not be shared with other users on different systems without further work.
- Editing a template could adversely impact existing projects.
- If stored as a copy
- Template updating can be tricky.
The initial feeling would be to include the template information as part of the project which would make the project portable.
Project Sharing (between users, local and/or remote)
We could have an option when saving a project to make the project “portable.” This could include not just including a copy of the template XML, but also model/mesh files that are not usually embedded in the project. Alternatively, users could be forced to deal with the project XML themselves (meaning they must send the XML along with other project files when sharing with another user). Finally, it might be possible to provide an “upload” service where project data (including the template and other project data) could be placed and indexed by SHA or some other key.
Export
Users should be able to choose a template to “export” so they can share it with others.
Options to export:
- to a local file of the user’s choosing
- upload to one of the site-specific URLs.
Uninstallation
Users should be able to “delete” templates. However, unless we maintain a database of projects that reference a template, perhaps it is better to consider the templates hidden rather than deleted. Otherwise, projects may not be readable if their template is deleted.