var aeq = (function (aeq) {
/**
- * [description]
+ * Sets or gets an attribute value for all objects in an array. When getting a
+ * value, it only returns the valure from the first object.
* @memberof aeq
+ * @see aeq.arrayEx.attr
* @method
- * @param {array} array [description]
- * @param {string} attributeName [description]
- * @param {Any} newValue [description]
- * @return {Any} [description]
+ * @param {Any[]} array The array of objects to get or set attribute
+ * values of.
+ * @param {string} attributeName The name of the attribute to get or set.
+ * @param {Any} [newValue] The value to set. If not given, will only get
+ * the value of the first object.
+ * @return {Any|undefined} When getting, the value of the attribute.
+ * When setting, `undefined`.
*/
aeq.attr = function(array, attributeName, newValue) {
var i, il;
@@ -120,7 +125,7 @@
* Gets all the item in a folder or project.
* @method
* @memberof aeq
- * @memberof aeq
* @param {FolderItem} [folder=app.project] The Folder to get items from.
- * @return {aeq.arrayEx} Array of Item objects
+ * @param {boolean} [deep=true] When `true`, gets items from
+ * subfolders as well.
+ * @return {aeq.arrayEx} Array of Item objects
*/
- getItems: function( folder ) {
- folder = aeq.project.getFolder(folder) || app.project;
- var items = aeq.normalizeCollection( folder.items );
+ getItems: function(folder, deep) {
+ // If no arguments are given, just return all items in project.
+ if (folder === undefined) {
+ return aeq.normalizeCollection(app.project.items);
+ }
+
+ deep = setDefault(deep, true);
+ folder = aeq.project.getFolder(folder);
+ if (folder === null) {
+ return aeq.arrayEx();
+ }
+
+ if (deep) {
+ return aeq.getItemsDeep(folder);
+ }
- return aeq.arrayEx( items );
+ return aeq.normalizeCollection(folder.items);
+ },
+
+ /**
+ * Returns an {@link aeq.arrayEx} with all items in a folder, and items in
+ * subfolders.
+ * @method
+ * @param {FolderItem} folder The folder to flatten.
+ * @return {aeq.arrayEx} ArrayEx with Item objects.
+ */
+ getItemsDeep: function(folder, returnArrayEx) {
+ // The returnArrayEx param is so we can skip the converting to arrayEx when
+ // recursing. It is not meant to be used outside of this function.
+ var item,
+ items = [],
+ len = folder.items.length;
+
+ for (var i=1; i <= len; i++) {
+ item = folder.items[i];
+ if (aeq.isFolderItem(item)) {
+ // Add all items in subfolder to the `items` array.
+ items.push.apply(items, aeq.getItemsDeep(item, false));
+ }
+ items.push(item);
+ }
+ // Skip converting to arrayEx when function is called by it self.
+ if (returnArrayEx === false) {
+ return items;
+ }
+ return aeq.arrayEx(items);
},
/**
@@ -75,24 +117,16 @@
dom.js
},
/**
- * Gets all the CompItems in the project
+ * Gets all the CompItems in the project. Or all CompItems in the given folder.
* @method
* @memberof aeq
+ * @param {FolderItem} [folder=app.project] The folder to get comps from.
+ * @param {boolean} [deep=true] Go through subfolders looking for comps.
* @return {aeq.arrayEx} Array of CompItems
*/
- getCompositions: function () {
- var arr = [];
- var len = app.project.items.length;
-
- for (var i=1; i <= len; i++)
- {
- var item = app.project.item(i);
-
- if (aeq.isComp(item))
- arr.push(item);
- }
-
- return aeq.arrayEx(arr);
+ getCompositions: function(folder, deep) {
+ var items = aeq.getItems(folder, deep)
+ return items.filter( aeq.isComp )
},
/**
@@ -501,7 +535,7 @@
Make sure you have node
diff --git a/docs/main.js.html b/docs/main.js.html
index 45f9a1a..4f1f201 100644
--- a/docs/main.js.html
+++ b/docs/main.js.html
@@ -22,7 +22,7 @@
return filePathStr.substr(0, filePathStr.lastIndexOf('.'));
},
+ /**
+ * Takes a file path or a file object, and returns a file object
+ * allows functions to be flexible in whether they take a path vs file
+ * @method
+ * @memberof aeq
+ * @param {File|string} filePath String path to a file, or file object
+ * @return {File} Resolved file object
+ */
+ getFileObject: function(filePath) {
+ return aeq.isFile(filePath) ? filePath : new File(filePath);
+ },
+
/**
* Gets target file by path or file object, or null if doesn't exist
* @method
@@ -224,6 +236,18 @@
modules/file.js
return aeq.arrayEx(files);
},
+ /**
+ * Takes a folder path or a folder object, and returns a folder object
+ * allows functions to be flexible in whether they take a path vs folder
+ * @method
+ * @memberof aeq
+ * @param {Folder|string} folderPath String path to a folder, or folder object
+ * @return {Folder} Resolved folder object
+ */
+ getFolderObject: function(folderPath) {
+ return aeq.isFolder(folderPath) ? folderPath : new Folder(folderPath);
+ },
+
/**
* Returns a folder, or null if it doesn't exist
* @method
@@ -255,13 +279,81 @@
modules/file.js
return folder;
},
+
+ /**
+ * Returns the contents of a specified file
+ * @method
+ * @memberof aeq
+ * @param {File|string} filePath Path or file to read
+ * @param {string} [encoding=UTF-8] Encoding method
+ * @return {string|null} Contents of the file, or null if file doesn't exist
+ */
+ readFile: function(filePath, encoding) {
+ var file = aeq.getFileObject(filePath),
+ contents;
+
+ encoding = setDefault(encoding, "UTF-8");
+
+ if (file.exists) {
+ if (File.isEncodingAvailable(encoding))
+ file.encoding = encoding;
+
+ file.open();
+ contents = file.read();
+ file.close();
+ return contents;
+ }
+ return null;
+ },
+
+ /**
+ * Writes data to a file, returns file
+ * @method
+ * @memberof aeq
+ * @param {File|string} filePath Path or file to write to
+ * @param {string} contents Data to write to the file
+ * @param {object} [options] Options for writing file.
+ * @param {boolean} [options.overwrite=false] `true` if file should be overwritten if exists.
+ * @param {string} [options.encoding="UTF-8"] Encoding method.
+ * @return {File|null} New file, or null if file was not written
+ * correctly or file exits and overwrite = false
+ */
+ writeFile: function(filePath, contents, options) {
+ var file = aeq.getFileObject(filePath);
+ options = aeq.setDefault(options, {});
+
+ if (file.exists && options.overwrite === false) {
+ return null
+ }
+
+ if (!file.exists) {
+ aeq.file.ensureFolderExists(file.path);
+ }
+
+ if (!aeq.isNullOrUndefined(options.encoding) && File.isEncodingAvailable(options.encoding)) {
+ file.encoding = options.encoding;
+ }
+
+ file.open("w");
+ var success = file.write(contents);
+ file.close();
+
+ if (success)
+ return file;
+
+ return null;
+ }
});
// Function aliases
aeq.pathSeparatorSymbol = aeq.file.pathSeparatorSymbol;
+aeq.getFileObject = aeq.file.getFileObject;
+aeq.getFolderObject = aeq.file.getFolderObject;
aeq.getFile = aeq.file.get = aeq.file.getFile;
aeq.getFiles = aeq.file.getFiles;
aeq.getFolder = aeq.file.getFolder;
+aeq.readFile = aeq.file.readFile;
+aeq.writeFile = aeq.file.writeFile;
return aeq;
}(aeq || {}));
@@ -277,7 +369,7 @@
getFolders: function(parentFolder){
var folders = aeq.getItems(parentFolder);
- return folders.filter(function(item){
- return aeq.isFolderItem(item);
- });
+ return folders.filter(aeq.isFolderItem);
},
/**
- * Find folder by name in target folder, or root
+ * Find folder by name in target folder.
* @method
* @memberof aeq.project
- * @param {string} name Folder name to find
- * @param {FolderItem|string} [parentFolder=app.project.root] Folder to search in by name or item, or root if undefined
- * @return {FolderItem} ArrayEx of folder items
+ * @param {string} name Folder name to find.
+ * @param {FolderItem|string} [parentFolder=app.project.root] Folder to search in by name or item, or root if undefined.
+ * @return {FolderItem|null} FolderItem with the name. Or `null` if not found.
*/
findFolder: function(name, parentFolder){
var folders = aeq.project.getFolders(parentFolder);
@@ -95,8 +91,10 @@
},
/**
- * Checks the arguments length to determine to get or set
- * and it needs an object to get or set attributes to.
+ * Sets or gets an attribute value for all objects in the array. When getting a
+ * value, it only returns the valure from the first object.
* @method
* @memberof aeq.arrayEx
- * @return {type} [description]
+ * @param {string} attributeName The name of the attribute to get or set.
+ * @param {Any} [newValue] The value to set. If not given, will only get
+ * the value of the first object.
+ * @return {Any} when getting, the value of the attribute.
+ * When setting, `undefined`.
* @see aeq.attr
*/
attr: function() {
@@ -328,7 +332,7 @@
diff --git a/docs/tutorial-Add motion blur to animated layers.html b/docs/tutorial-Add motion blur to animated layers.html
index 34de664..b6033d0 100644
--- a/docs/tutorial-Add motion blur to animated layers.html
+++ b/docs/tutorial-Add motion blur to animated layers.html
@@ -22,7 +22,7 @@
@@ -113,7 +113,7 @@
Add motion blur to animated layers
The goal of this script is to turn
diff --git a/docs/types.js.html b/docs/types.js.html
index 60365b8..5e249f1 100644
--- a/docs/types.js.html
+++ b/docs/types.js.html
@@ -22,7 +22,7 @@