File Location Editor

The File Locations dialog is where you see the file locations Simplebim knows about, add locations of your own, rename them, point them at folders and remove them again. File locations are what file and folder settings refer to instead of bare paths, so that the same configuration can point to different folders on different computers.

How a file or folder setting uses a location is covered in the Configuration Editor article. What happens to a dataflow when its locations change is covered in Dataflow Palette.

What a File Location Is

A file location is a named folder. Instead of storing C:\Projects\Tower\Exports\model.ifc, a file setting stores the location Exports plus the file model.ifc. Move the project, or open the same dataflow on another computer, and you only change where Exports points — every setting that uses it follows.

A location has:

a name, which is also how settings refer to it;
a parent: either This PC, meaning the folder is an ordinary Windows path, or another location, meaning the folder is relative to that one. Locations can be chained — Exports inside Project inside This PC;
a folder: the path, absolute under This PC, relative under any other parent;
a scope, which says who owns the location and where it is visible, see Scopes.

Two locations are built in and behave specially.

This PC points to the root of the local file system. It has no folder of its own; a location under This PC holds a full Windows path.

Current points to the folder of the model that is currently open or imported. Simplebim moves it whenever you open another model, so you cannot edit it.

Where You Meet the File Locations Dialog

The dialog always edits the locations of one context, named in its title, File Locations: dataflow. You reach it from two places:

File Locations on the toolbar of the Dataflow palette opens it for the current dataflow.
The location drop-down of a file or folder setting inside a dataflow step has an edit button at its right end, which opens the same dialog. When you close it with OK, the drop-down is refreshed and the location you had selected in the dialog is selected in the setting.

Either way the dialog shows the same list and the same locations are editable.

The Dialog at a Glance

Add and Delete buttons — above the list: + adds a location, the bin deletes the selected one.
The list — one row per location visible in this context, see The List of Locations. Click a row to select it.
Details — the Scope, Name and Folder of the selected location. Locations you may change show edit boxes here; the others show plain text.
OK and Cancel — OK applies everything you did in the dialog; Cancel throws all of it away. Nothing is applied before OK.

Changes you make are shown in the list as you make them — a changed name or folder turns blue, a deleted row turns red and struck through — but they only take effect when you click OK.

The List of Locations

Icon — a pencil when you can edit the row, a lock when you cannot. See Which Locations You Can Change.

Scope — who owns the location: System, User or Dataflow.

Parent(s) — the chain of locations this one is relative to, ending in an arrow: Project →. Empty for a location directly under This PC.

Name — the name of the location, which is also how settings refer to it.

Folder — the full folder, with the part inherited from the parent chain in grey and the location's own folder in black.

Only the locations that belong in the current context are listed. A location set up for use in dataflows is shown; one that is not, is not.

Scopes

Locations live in three nested scopes. Each scope sees the ones above it.

System holds the built-in locations Simplebim creates at start-up — This PC, Current, the dataflow and template folders. Visible everywhere.

User holds locations set up on this computer for you, kept in your settings. Visible everywhere, when they are flagged for the context.

Dataflow holds locations that belong to the current dataflow and are saved in its file. Visible only while that dataflow is open.

The dialog edits one scope at a time, the one of its context — for File Locations: dataflow that is the Dataflow scope. Locations of the other scopes are listed so that you can see them and use them as parents, but they are locked.

The Parent(s) Column

A location whose folder is relative to another location shows that location's name here, and if that one has a parent too, the whole chain: Project → Phase 2 →. The chain is read from the list as it currently is, so renaming a parent updates the chain of its children on the spot, and the changed chain turns blue.

The Folder Column

The column shows the folder the location resolves to right now:

the part that comes from the parent chain in grey;
the location's own folder in black, or in blue once you have changed it.

Change the folder of a parent and the grey part of every location under it changes with it.

The two built-in locations show a description instead of a path: <The root of the local file system> for This PC, and <The folder of the currently opened/imported model> for Current while no model is open.

Which Locations You Can Change

A row gets a pencil when at least its name or its folder can be changed, a lock otherwise. The rules:

System locations never change their name, and the two shown in the dataflow context — This PC and Current — cannot change their folder either.
Locations of another scope than the one the dialog edits are locked. In the dataflow dialog that means every System and User location.
Locations of the edited scope can be renamed, repointed and deleted.

So in File Locations: dataflow, the rows with a pencil are the dataflow's own locations, and only those.

Editing a Location

Click a row and its details appear below the list. For a location you can change, Name and Folder are edit boxes; Scope is always read-only.

Name

Type the new name. The row's Name cell follows as you type and turns blue when it differs from the name the location had when the dialog opened. Names are compared without regard to capitalisation.

Two names are not accepted, and the rename is quietly reverted when you click OK:

a name that is already in use by another location, in the list or elsewhere — a location that is not shown in this context still counts;
a name containing ://.

A renamed location changes more than its label; see Renaming and What It Changes.

Parent Location and Folder

The Folder row has two parts.

Parent drop-down — the location this one is relative to. This PC means the folder box holds a full path. Any other entry means the folder box holds a path inside that location.

Folder box — the path. Type it, or use the … button.

The parent drop-down offers the locations of this context except the one you are editing, and except locations of a scope narrower than the one you are editing — a location cannot depend on one that will not be there when it is used. Pick a parent and the row's Folder column shows the inherited part in grey straight away; the folder box keeps what it had, so adjust it if the path was absolute before.

Browse and Reset

… (Browse) opens the folder browser, starting at the folder the location currently resolves to — or the nearest part of it that exists. Pick a folder. When the parent is another location and the folder you picked lies inside it, only the part inside is stored; otherwise the full path is stored.

Reset is only shown for a location that has a default folder — the built-in user folders, for example. It puts the default back into the folder box.

Adding a Location

Click + above the list. A new row appears at the bottom, selected, in the scope the dialog edits, with an empty name and an empty folder under This PC. Fill in the Name and the Folder in the details below.

A new row that still has no name when you click OK is simply dropped, so a row added by mistake does no harm — leave it empty or delete it.

A new location is created for the context of the dialog: one added in File Locations: dataflow is a dataflow location, saved with the dataflow and listed in the location drop-downs of its steps.

Deleting a Location

Select a row and click the bin. The row turns red and struck through; it is removed when you click OK, and Cancel brings it back.

The bin is disabled when the selected location cannot be deleted:

a System location;
a location of another scope than the one the dialog edits;
a location that is the parent of another location in the list. Repoint or delete the child first.

The name of a deleted location is free again at once: a new row may take it in the same session.

Renaming and What It Changes

Settings refer to a location by its name, so a renamed location is, to them, a different location. When you click OK, the editor takes care of the consequences inside the dialog:

every location in the edited scope whose parent was the renamed location now refers to the new name;
when two locations swap names, or a rename chains through several rows, all of them end up right — renames are applied together, not one by one.

What lies outside the dialog is updated by whoever opened it:

opened from the Dataflow palette, every file and folder setting of every step that used the old name is switched to the new one, and the dataflow is marked as changed;
opened from a setting's location drop-down, that setting and the other settings of the same step follow, and the setting keeps the location selected under its new name.

Renaming does not move any files. It changes what the name stands for, not what is on disk.

Keeping or Discarding Your Changes

Nothing you do in the dialog is applied until you click OK:

OK applies renames, folder changes, additions and deletions together, in that order, and hands the result back to the palette or the setting that opened the dialog. From the Dataflow palette the dataflow is then marked as changed — save it to keep the locations in its file.
Cancel discards everything, including deletions; the list is as it was when the dialog opened.

There is no undo inside the dialog. To take back one change, retype the old name or folder before clicking OK, or cancel and start over.

Troubleshooting

Every row has a lock and I cannot edit anything.
Only the locations of the dialog's own scope are editable. In File Locations: dataflow those are the dataflow's locations, and a new dataflow has none yet. Click + to add one.

The name I typed came back as the old name.
The name is already in use by another location — possibly one that is not shown in this context — or it contains ://. Pick another name.

The bin is greyed out.
The selected location is a System location, belongs to another scope, or is the parent of another location in the list. Change the child's parent first, then delete.

The folder looks shorter than the one I browsed to.
The parent is another location and the folder you picked lies inside it, so only the part inside is stored. The grey part of the Folder column shows the rest; together they are the full path.

I picked a parent and the folder became wrong.
The folder box is not changed when you pick a parent, so a full path typed under This PC is now read relative to the new parent. Edit the folder box or browse again.

The location I want as a parent is not in the drop-down.
A location cannot be its own parent, and it cannot depend on a location of a narrower scope than its own. Locations that are not set up for this context are not offered either.

The folder browser opened somewhere unexpected.
It starts at the folder the location currently resolves to, or at the deepest part of that path that exists on this computer. A parent that points nowhere yet sends it to the top.

I renamed a location and a step now shows a red location name.
The step's setting still refers to the old name. This happens when the rename was made somewhere the step could not follow — for example in a dataflow file edited by hand. Pick the location again in the setting's drop-down.

Current shows no folder.
No model is open. Current follows the model; open or import one and it points at that model's folder.