PhotoShop Scripting
        by mlk : Hot Summer Month of 2004

IV. Using a Text File as a Database
Opening and using a text file, using filters, using history states, copy/pasting

 
[ By the end of the script you'll have created 20 business cards]

This script will show you that we can use a database in Photoshop to create dynamically driven graphics. With this scripts we will be doing a set of 20 business cards with each individual’s info taken from a text file. (now imagine you have a huge company of 2000 people – that would be appreciated….).

I’ve decided that out of these 20 people there will be 3 different groups (we’ll call them Engineering, Service, Marketing). Notice here that I’ve typed the whole database by hand (well; actually the names were randomly generated with the help of this site, and phone/fax numbers were made by Javascript) – usually (and what I’ve done in the past) is take and Excel file containing all the data, parse the file in MS Word with ‘mailmerge’ to create my simple text file. I’ll provide help if anyone ever needs too – but this isn’t Photoshop scripting so I’ll stay out of it for now.

Now first of all here is our database (as I said previously it could/should be dynamically filled, first because it saves time and secondly because there is a format to respect - see 'tip' below to see why). The text below is an excerpt from the database, take the one from the text file to make the script work.

i. Code (explained below)

if(documents.length==0){
   alert("You need to have your template business card open (-businessCardTemplate.psd-)")
}else{

   function capitalizeLastName(inputName){
      var newNameArray = inputName.split(" ");
      var outPutName = newNameArray[0]+" "+newNameArray[1].toUpperCase();
      return outPutName;
   }

   function makeEmail(inputName){
      inputName = inputName.toLowerCase();
      var outPutName = inputName.replace(" ",".")+"@kfagency.com";
      return outPutName;
   }

   var defaultRulerUnits = preferences.rulerUnits;
   preferences.rulerUnits = Units.INCHES;

   var bizTemplate = activeDocument;
   var newDoc = documents.add(3.5, 2, 150.0, "BusCars Compilation",DocumentMode.RGB, DocumentFill.WHITE);

   activeDocument = bizTemplate;

   var dbText = new File("/G/db.txt");
   dbText.open ('r');

   var jobPositionArray = ["engineering","services","marketing"];
   var globalArray = new Array(20);

   for(a=0;a<=19;a++){
      globalArray[a] = new Array(4);
   }

      for(a=1;a<=4;a++){
         dbText.readln();
   }
   for(a=1;a<=20;a++){
      for(b=1;b<=4;b++){
         globalArray[a-1][b-1] = dbText.readln();
       }
      dbText.readln();
   }

   for(a=1;a<=20;a++){
   var tempName = globalArray[a-1][0];
   var emailAddress = makeEmail(tempName);
   tempName = capitalizeLastName(tempName);

   if(tempName.length >= 15){
   bizTemplate.layers[0].textItem.size = 7.5
   
    }

   bizTemplate.layers[0].textItem.contents = tempName;
   bizTemplate.layers[1].textItem.contents = "KFA "+jobPositionArray[globalArray[a-1][1]-1];
   bizTemplate.layers[2].textItem.contents = "Tel: "+globalArray[a-1][2]+"\u000DFax: "+globalArray[a-1][3];
   bizTemplate.layers[3].textItem.contents = emailAddress;
   bizTemplate.layers[4].textItem.contents = bizTemplate.layers[4].textItem.contents + " " + a;

   bizTemplate.flatten();
   bizTemplate.layers[0].applyAddNoise(1.00,NoiseDistribution.UNIFORM,0);
   bizTemplate.selection.selectAll();
   bizTemplate.selection.copy();

   activeDocument = newDoc;
   newDoc.paste();
   newDoc.layers[0].name = tempName;

   activeDocument = bizTemplate
   bizTemplate.activeHistoryState = bizTemplate.historyStates[0]
   }

}

preferences.rulerUnits = defaultRulerUnits;

ii. Code explanation and syntax details

Here is the outline of what happens:

And now, onto the code.

The first thing the script does is check if a document is open (namely it should be our business card) with 'if(documents.length==0)' . It doesn't check however if you have opened the proper document (ie with the same number of text layers and with the proper size). This is just intended for those who use the script and forget about opening up the original business card file.

The next steps are functions. In Javascript you can create functions to save coding for later on. Here the two functions declared ('capitalizeLastName(var)' and 'makeEmail(var)') are specific to our script; the first one will capitalize the last name ("John Doe" becomes "John DOE") the second one will make the email adress of our fake business agency ("John Doe" becomes "john.does@kfagency.com").

I'll explain how the first function works, and you'll guess the second. If you look at the rest code (the line where we call the first function) you'll see 'tempName = capitalizeLastName(tempName);'. Here we have a string variable 'tempName' (its value will be "John Doe", which is the type of name data we would find in our database) we assign to 'tempName' its a new value, which is the one it will have once its been through our first function. Notice our function is 'capitalizeLastName(inputName)' the variable we passed was 'tempName'; this is why 'tempName' is now 'inputName' (and 'inputName' has for value "John Doe").

'var newNameArray = inputName.split(" ");' creates an array of words, it splits our string according to a character (here the space " " character). It means that at this moment 'newNameArray' has for value ["John","Doe"].

'var outPutName = newNameArray[0]+" "+newNameArray[1].toUpperCase();'. Here we create a new variable which is made of the first item of the array ("John"), a space character, and the uppercase version of the second item of the array ("DOE"). "John Doe" has become "John DOE".
But the function is limited. If for instance the variable was "James Patrick Burbank", the function would return "James PATRICK" and not "James Patrick BURBANK". You could solve this problem with a few more lines of code, but since our database does not contain such name, we don't need to.

'return outPutName' is necessary to 'return' a value from the function. Since we used earlier 'tempName = capitalizeLastName(tempName)' well actually here 'tempName' becomes 'outputName' (and if you remember correctly we fetched 'outputName' initially from the first value of 'tempName' that was turned into a capitalized last name).
The second function to turn the name into an email works a bit the same way, except that we turn the spaces (" ") into dots ("."), lowercase the whole name and add "@kfagency.com".. That way "John Doe" becomes "john.doe@kfagency.com".

The steps that follow you should know about, we create a new document (note that it's the same size as our orignal business card template, change that according to your needs).
We then turn the business card template into the activeDocument, because it's the one we're going to need to work with.

The next steps are the central piece of the script; opening up the text file: 'var dbText = new File("/G/db.txt")' and 'dbText.open ('r')' as you see we will now refer to our text file as 'dbText'. We opened the file in read ('r') mode, but you can open it up in write mode ('w') and actually create your own text files. It could become quite handy ! Note here that even though we declared the new file, we still needed to open it with 'dbText.open ('r')'. (Mac users might also have issues with the file location, here the file is G:\db.txt for PCs and I guess desktop>g>db.txt for Macs).

The next step set up our database so we can fill it up with info. Now we have 20 employee, each with four info: Name, Job Position, Fax & Telephone; hence the creation of a first 'big' array of 20 items, and then the loop which fills each item with a new array of 4 items... This means that name will always be located on position 'globalArray[x][0]', job positions will always be located in positions 'globalArray[x][1]' and so on (remember once again that arrays start on position 0, not 1).

The note explains the following code:

for(a=1;a<=20;a++){
  for(b=1;b<=4;b++){
    globalArray[a-1][b-1] = dbText.readln();
  }
  dbText.readln();
}
The first loop go from 1 to 20, because we have 20 cards to do; then the second loop reads four lines of the text database and fill the array accordingly. We need to add and extra 'dbText.readln()' for nothing because after the four lines there is a blank line...

The array is now filled with all the data, we're going to do the filling work (which you should know by now...).

The new loop goes from 1 to 20, to create our 20 business cards. 'var tempName = globalArray[a-1][0]' fetches the name of the employee because we need it to do the capitalization work 'tempName' and the email adress 'emailAddress' (using the functions at the beginning of the script).
After having run the script once I noticed that some names were larger than the size of the business card, which is why the following code is used (reduces the font size of the 'name' text layer of the business cards when names are over 15 characters):

if(tempName.length >= 15){
  bizTemplate.layers[0].textItem.size = 7.5
}

The rest of the filling code then ('bizTemplate.layers[0].textItem.contents = tempName', etc...) is pretty self explanatory.

Since our document only has one layer left (the background layer) when we do the copying, we don't need to set an active layer. You should be able to understing the copy/paste code of the script by looking at the note above.
'newDoc.layers[0].name = tempName' sets the name of the newly created layer (pasted layer) to that of the employee name (that we had used previously to fill in the text layers)

activeDocument = bizTemplate;
bizTemplate.activeHistoryState = bizTemplate.historyStates[0];

These last steps return to our original (bizTemplate) document and set it to how it was originally. Notice here we used the history states of your document, where 'historyStates[0]' is the state of the document when you opened it. You can also set a variable to be specific history state and come back to it later ! Use the code 'var myHistoryState = myDoc.activeHistoryState' and go to it later with 'myDoc.activeHistoryState = myHistoryState'

The last step of the script as you know now set back the original working units to whatever they were... hope this section covered things you had no idea about !

Onto the PS jibberish: Non-documented functions: using the script listener.