Step 3) Modifying content in your local development environment

Creating, modifying, and deleting project content

In this step, we will see how to edit project content.
For this, the local development state

• can be changed internally using the local FirstSpirit project instance (recommended) or
• externally, directly in the file system (limitations apply)

See figure Step 3) Modification.

Initial situation

Preparation

The developer’s local repository has already been updated using the version control system (see 1) Update). During this process, the central development state was transferred out of the remote repository. The project content and, if applicable, project properties are in the Sync directory (file system) and ready for import.

Before further development, all content is imported into the local FirstSpirit project instance (see 2) Import).

Editing project content

In the FirstSpirit project (internally)

Templates are developed directly in the local FirstSpirit project instance.

Here you can do the following:

• creating objects
• modifying objects
• moving objects
• deleting objects.

Each developer works in his own local environment. All changes between the (local) project instance and the development state in the (local) file system are performed using the export and import functions in “External Synchronization”:

In the file system (externally)

At file system level, project contents and properties that are created via External Synchronization are available in a format “that is legible to humans”. Project contents, such as a CSS file from the project’s Media Store, are also stored as a CSS file in the file system. The folder structures from the project are used in the file system. File names and further information from the project are also taken into account.

This makes it easy to find and edit project content, even in the file system – outside of the FirstSpirit project instance. However, this content then has to be imported back into the project (see Next steps).

At file system level, you can

• modify objects
• move objects

Limitations (external editing)

Do not copy elements into the file system! Copies of elements cannot be created at file system level. Background: Internal information (e.g., IDs, GIDs) would also be copied in this case. This leads to duplicate IDs when importing to the FirstSpirit project.

Do not create elements in the file system! Elements must not be created at file system level. Background: The internal meta-information needed to import the content back to a FirstSpirit project cannot be generated manually. The missing information would then lead to problems during the import process.

Do not delete elements in the file system! Elements must not be deleted at file system level. Background: In this case, simply removing the object in question will not suffice. The internal meta-information would have to be adjusted manually as well.

Internal meta-information must not be modified! (Folder “.FirstSpirit”) The folder “.FirstSpirit” contains internal meta-information for the successful synchronization of external content with the FirstSpirit project. This internal data must not be changed. Exported project content with the identifier FS_ must not be edited externally either. Background: When exporting FirstSpirit content via External Synchronization, technical files are also exported as well. These contain information such as the file’s MIME type, CRC checksums, reference tables, or other general internal information. These files must not be changed.

A high level of caution must be applied when moving elements in the file system. Background: At file system level, content can also be moved into project structures where the content is no longer valid (e.g., a folder from the Media Store moved to another FirstSpirit area, e.g., “Contents”). Incorrect move actions then lead to errors when importing the information to the project.

Next steps

Import the project contents again (in the event of external changes)

The following applies for all external changes: If project content has been changed externally (in other words, outside the FirstSpirit environment), the content first has to be imported into the local FirstSpirit project instance before exporting and transferring it into the central state. Only then should it be exported into the local file system.

Why is this important? In addition to the actual content of the project, additional internal information is created when exporting via External Synchronization. When importing the content into a FirstSpirit project instance, this makes sure that all content in the project is assigned and created correctly, dependencies can be taken into account, etc.

When changing the content at file system level (for example, when deleting objects without permission), inconsistent states may occur within the project as the internal meta-information no longer matches the actual content.

To make sure the invalid development state is not accidentally transferred to the central development state, external changes should always be imported into the local project instance first before being transferred into the central development state (commit/push).

If external changes can be imported without any errors, the project content can then be exported.

Exporting project content

If a stable state has been achieved once work on a work package is complete, the developer must export the project data out of his FirstSpirit project instance.

Continue with Step 4) Export.