Question about stationery and stationery scripts

EagleFiler
,
1

Stationery and stationery scripts

Manual sections 5.2.5 and 7.3

I have a question about stationery and stationery scripts.

It can best be illustrated by an example.

Say I want to create a project folder, and within that a text file describing the project. I can set that up as stationery, using a folder ProjectStationery and within it a text file ProjectDescription.txt

If invoked, it would create a literal copy of the folder and file at the current location in EagleFiler.

If I wanted to customize the name, say to Project-154, I could employ a stationery script. Within this would be a metadata handler, which receives as a parameter an AppleScript record with information on the current context. Based on this, and perhaps the current date or prompted information, the handler returns an AppleScript record which will be used to set the EagleFiler metadata on the file. So I can customize the folder name, title, and tags: ProjectStationery becomes Project-154.

But say I wanted the text file to also have a custom name and content. This raises some questions.

Question 1: Does the instance of the stationery exist at the time the handler is run?

If so, I could simply rename the text file and append text to it as needed. If not, I’d be out of luck.

But it raises another question.

Question 2: Does renaming a file here (by script) violate EagleFiler’s rules?

The file would be renamed within EagleFiler, but not by EagleFiler, so would EagleFiler pick up the change?

You might get around this by using the script to create the file in the first place. EagleFiler could pick up a newly created file.

Finally, a third question.

Question 3: The _context parameter to the metadata handler includes the path to the library and the immediate folder name within the library, but not the path to that folder. How would you know where to create a file?

As an aside, there is a typo in the documentation of 7.3 under “Stationery Script Details”: the record key libraryPath is misspelled “libaryPath”.

2

The metadata handler is called before a new EagleFiler record is created from the stationery. So, if you want, your script could modify the file at the stationeryPath, and the changes would be reflected in the new record. You should not rename the stationery file. Instead, have the metadata handler return the filename that you want to use.

The stationery file is not really subject to the same rules because it’s not a record in the library and not stored in the library’s Files folder. Renaming stationery in the middle of using the New Record command would cause problems. Otherwise, it’s OK to rename stationery from outside of EagleFiler (there’s no interface within it), and it should detect the changes automatically.

I’ll make a note to pass in the full destination path (or perhaps the EagleFiler record for the folder), but the stationery system is not designed for you to create the file yourself. You could, of course, do the whole thing yourself via AppleScript instead of using stationery, but that doesn’t seem necessary in your case.

Fixed, thanks. This is just a documentation bug. The code was already using the correct spelling.

3

Thank you, Michael.

A couple points of clarification:

My thinking was that the stationery folder/file would be copied, just as if there was no stationery script, and then the script would run and the handler would reassign any of the EagleFiler metadata to complete the task. The folder/file copy does not take place until after the handler has run?

Again, I was operating on the assumption that the stationery folder/file had already been copied to the library but had not yet been renamed by the handler. It would be the version that was copied to the library that would be renamed.

If a general AppleScript needed to rename a file, it should do so by addressing EagleFiler, rather than the Finder or the command line, correct?

4

Correct:

  1. Call handler.
  2. Copy file directly to the specified name.
  3. Assign metadata.

Yes.

5

To be clear, the metadata returned from the script determines the name of the top-level stationery item, which in this case is a folder. If you want to create or rename the text file, you could do that directly in your script.

6

Thank you, Michael.

Sometimes, questions beget other questions.

A stationery script must contain a metadata handler. Is it correct that only that handler code (and any code called by it) is executed when you create a new record using that stationery? That is, any other code in that script is ignored, so there is no opportunity to do anything beyond what the handler does, correct?

7

Yes.

There’s only one hook that EagleFiler calls, if that’s what you mean. As you say, you can call other code from within the handler. You can also leave other inert code outside the handler, e.g. for testing purposes.

8

Do you think there would be merit in offering additional handlers or hooks in the stationery script? Perhaps one called before the addition of the new file, which might nix the whole operation if conditions were wrong, and one called after the files were created, to perform actions that required that those files exist?

9

Could you give some examples of how you might use these?

10

A before handler might let you impose restrictions as to when the stationery item could be added. For example, it could check the environment and limit the use of the stationery to certain folders, or prevent a duplicate from being added.

An after handler might add custom data to a text file, or for a folder, apply custom names to child items in a stationery hierarchy.

Of course, this could be done through a regular AppleScript, but I thought it might be easier to just write the handler code and piggyback on the stationery functionality.

11

Thanks.