diff --git a/docs/client/api.html b/docs/client/api.html index 7fcdbde1fc..76cd3994ed 100644 --- a/docs/client/api.html +++ b/docs/client/api.html @@ -2945,6 +2945,25 @@ by spammers.) 'This is a test of Email.send.'); {{/better_markdown}} + +

Assets

+ +{{#better_markdown}} +`Assets` allows server code in a Meteor application to access static server +assets, which are located in the `private` subdirectory of an application's +tree. + +{{> api_box assets_getText }} +{{> api_box assets_getBinary }} + +Static server assets are included by placing them in the application's `private` +subdirectory. For example, if an application's `private` subdirectory includes a +directory called `nested` with a file called `data.txt` inside it, then server +code can read `data.txt` by running: + + var data = Assets.getText('nested/data.txt'); +{{/better_markdown}} + diff --git a/docs/client/api.js b/docs/client/api.js index 0829aed171..e14de34dab 100644 --- a/docs/client/api.js +++ b/docs/client/api.js @@ -1811,3 +1811,43 @@ Template.api.email_send = { } ] }; + +Template.api.assets_getText = { + id: "assets_getText", + name: "Assets.getText(assetPath, [asyncCallback])", + locus: "Server", + descr: ["Retrieve the contents of the static server asset as a UTF8-encoded string."], + args: [ + {name: "assetPath", + type: "String", + descr: "The path of the asset, relative to the application's " + + "`private` subdirectory." + }, + {name: "asyncCallback", + type: "Function", + descr: "Optional callback, which is called asynchronously with the error " + + "or result after the function is complete. If not provided, the function " + + "runs synchronously." + } + ] +}; + +Template.api.assets_getBinary = { + id: "assets_getBinary", + name: "Assets.getBinary(assetPath, [asyncCallback])", + locus: "Server", + descr: ["Retrieve the contents of the static server asset as an EJSON Binary."], + args: [ + {name: "assetPath", + type: "String", + descr: "The path of the asset, relative to the application's " + + "`private` subdirectory." + }, + {name: "asyncCallback", + type: "Function", + descr: "Optional callback, which is called asynchronously with the error " + + "or result after the function is complete. If not provided, the function " + + "runs synchronously." + } + ] +}; diff --git a/docs/client/concepts.html b/docs/client/concepts.html index f6cb1c6e00..107ff6d416 100644 --- a/docs/client/concepts.html +++ b/docs/client/concepts.html @@ -28,17 +28,23 @@ CSS rules, and static assets. Meteor automates the packaging and transmission of these different components. And, it is quite flexible about how you choose to structure those components in your file tree. -The only server asset is JavaScript. Meteor gathers all your JavaScript -files, excluding anything under the `client` -and `public` subdirectories, and loads them into a Node.js +The only server assets are JavaScript and files in the `private` subdirectory. +Meteor gathers all your JavaScript +files, excluding anything under the `client`, `public`, and `private` +subdirectories, and loads them into a Node.js server instance inside a fiber. In Meteor, your server code runs in a single thread per request, not in the asynchronous callback style typical of Node. We find the linear execution model a better fit for the typical server code in a Meteor application. +Meteor gathers any files under the `private` subdirectory and makes the contents +of these files available to server code via the [`Assets`](#assets) API. The +`private` subdirectory is the place for any files that should be accessible to +server code but not served to the client, like private data files. + There are more assets to consider on the client side. Meteor -gathers all JavaScript files in your tree with the exception of -the `server` and `public` subdirectories for the +gathers all JavaScript files in your tree, with the exception of +the `server`, `public`, and `private` subdirectories, for the client. It minifies this bundle and serves it to each new client. You're free to use a single JavaScript file for your entire application, or create a nested tree of separate files, or anything in between. @@ -61,8 +67,8 @@ containing passwords or authentication mechanisms, should be kept in the `server` directory. CSS files are gathered together as well: the client will get a bundle with all -the CSS in your tree (excluding the `server` -and `public` subdirectories). +the CSS in your tree (excluding the `server`, +`public`, and `private` subdirectories). In development mode, JavaScript and CSS files are sent individually to make debugging easier. diff --git a/docs/client/docs.js b/docs/client/docs.js index 7ef70bca80..60fe71184c 100644 --- a/docs/client/docs.js +++ b/docs/client/docs.js @@ -314,6 +314,10 @@ var toc = [ ], "Email", [ "Email.send" + ], + {name: "Assets", id: "assets"}, [ + {name: "Assets.getText", id: "assets_getText"}, + {name: "Assets.getBinary", id: "assets_getBinary"} ] ],