@@ -1,5 +1,9 @@
v0.7
+- Added yaws_arg:add_to_opaque/2, yaws_arg:add_all_to_opaque/2, and
+yaws_arg:get_opaque_val/2 to simplify accessing the 'opaque' field of the
+Yaws arg record.
+
- Added support for multiple databases. More information is in the
documentation. (yariv)
CHANGELOG.txt
@@ -99,7 +99,7 @@ many-to-many relations.)</p>
<h2><a name="types">Data Types</a></h2>
<h3><a name="type-driver">driver()</a></h3>
-<p><tt>driver() = {Driver, Options::<a href="#type-proplist">proplist()</a>} | {Driver, Options::<a href="#type-proplist">proplist()</a>, [<a href="#type-pool">pool()</a>]}</tt></p>
+<p><tt>driver() = atom() | {Driver::atom(), DriverOptions::<a href="#type-proplist">proplist()</a>} | {Driver::atom(), DriverOptions::<a href="#type-proplist">proplist()</a>, [<a href="#type-pool">pool()</a>]}</tt></p>
<h3><a name="type-pool">pool()</a></h3>
@@ -107,8 +107,11 @@ many-to-many relations.)</p>
<h2><a name="index">Function Index</a></h2>
-<table width="100%" border="1"><tr><td valign="top"><a href="#code_gen-2">code_gen/2</a></td><td>Generate code for the list of modules using the provided drivers.</td></tr>
-<tr><td valign="top"><a href="#code_gen-3">code_gen/3</a></td><td/></tr>
+<table width="100%" border="1"><tr><td valign="top"><a href="#code_gen-2">code_gen/2</a></td><td>Equivalent to <a href="#code_gen-3"><tt>code_gen(Modules, Drivers, [])</tt></a>.
+</td></tr>
+<tr><td valign="top"><a href="#code_gen-3">code_gen/3</a></td><td>Equivalent to <a href="#code_gen-4"><tt>code_gen(Modules, Drivers, Options, [])</tt></a>.
+</td></tr>
+<tr><td valign="top"><a href="#code_gen-4">code_gen/4</a></td><td>Generate code for the list of modules using the provided drivers.</td></tr>
<tr><td valign="top"><a href="#start-1">start/1</a></td><td>Start an ErlyDB session for the driver using the driver's default
options.</td></tr>
<tr><td valign="top"><a href="#start-2">start/2</a></td><td>Start an ErlyDB sessions for the driver using the list of
@@ -118,94 +121,132 @@ many-to-many relations.)</p>
<h2><a name="functions">Function Details</a></h2>
<h3><a name="code_gen-2">code_gen/2</a></h3>
-<p><tt>code_gen(Modules::[Module::atom() | string()], Options::[<a href="#type-driver">driver()</a>]) -> ok | {error, Err}</tt></p>
+<tt>code_gen(Modules, Drivers) -> term()
+</tt><p>Equivalent to <a href="#code_gen-3"><tt>code_gen(Modules, Drivers, [])</tt></a>.</p>
+
+
+<h3><a name="code_gen-3">code_gen/3</a></h3>
+<tt>code_gen(Modules, Drivers, Options) -> term()
+</tt><p>Equivalent to <a href="#code_gen-4"><tt>code_gen(Modules, Drivers, Options, [])</tt></a>.</p>
+
+
+<h3><a name="code_gen-4">code_gen/4</a></h3>
+<p><tt>code_gen(Modules::[Module::atom() | string()], Driver::[<a href="#type-driver">driver()</a>] | <a href="#type-driver">driver()</a>, Options::[term()], IncludePaths::[IncludePath::string()]) -> ok | {error, Err}</tt></p>
<p><p>Generate code for the list of modules using the provided drivers.</p>
+ <p>If you're using ErlyWeb, you shouldn't need to call this function directly.
+ Instead, refer to <a href="erlyweb.html#compile-2"><code>erlyweb:compile/2</code></a>.</p>
+
+ <h4><a name="Usage">Usage</a></h4>
+
<p>In ErlyWeb 0.7, the signature for this function has changed.
ErlyDB used to support only a single driver with a single connection
pool in a session. As of ErlyWeb 0.7, ErlyDB supports multiple
drivers in a session, and multiple connection pools for each
driver.</p>
- <p>The 'Modules' parameter is a list of files or modules for which to
+ <h5><a name="Modules">Modules</a></h5><p>
+The 'Modules' parameter is a list of files or modules for which to
generate ErlyDB code. If a list item is an atom, ErlyDB assumes it's
-a module that has been loaded into the VM or that resides in the
+a module that has been loaded into the VM or that resides in the VM's
code path. In either case, the module's source code should be discoverable
-either through path conventions or because it includes debug_info.
-If a list item is a string, ErlyDB treats it as a file name (relative
+either through Erlang's path conventions or because the module
+was compiled with debug_info.</p>
+
+ <p>If a list item is a string, ErlyDB treats it as a file name (relative
or absolute) and attempts to read it from disk.</p>
- <p>The 'Driver's parameter is a list of Driver::atom(),
-{Driver::atom(), Options::proplist()} or
-{Driver::atom(), Options::proplist(), Pools::pool()} tuples.
-The first tuple in the Drivers list is
+ <h5><a name="Drivers">Drivers</a></h5><p>
+ The 'Drivers' parameter is either a single element or a list of
+ elements of the form
+ <code>Driver::atom()</code>,
+ <code>{Driver::atom(), DriverOptions::proplist()}</code>, or
+ <code>{Driver::atom(), DriverOptions::proplist(), Pools::pool()}</code>.</p>
+
+ <p>The first element in the Drivers list is
the default driver that ErlyDB will use for all modules that don't
override the driver option.</p>
- <p>Driver can be 'mysql', 'psql' or 'mnesia'. Options is a list of
+ <p>'Driver' can be <code>mysql</code>, <code>psql</code> or <code>mnesia</code>. 'Options' is a list of
driver-specific options. For a list of available options, refer to
the driver's documentation.</p>
- <p>Pools is a list of available connection pools for the driver.
-Note that the driver must be started and the pools must be connected
-before code_gen/2 is called. Each item in Pools is an atom indicating
-the pool id, or a tuple of the form {default, PoolId}, indicating
-that this pool will be used as the default pool for the driver.
-If you don't provide a {default, PoolId} pool option, ErlyDB will use
-the built-in default pool id.</p>
+ <p>'DriverOptions' is a property list that contains driver-specific options
+(e.g. '{allow_unsafe_statements, Bool}').
+For more information refer to the driver's documentation.</p>
+
+ <p>'Pools' is a list of available connection pools for the driver.
+ Note that the driver must be started and the pools must be connected
+ before code_gen/2 is called. Each item in 'Pools' is an atom indicating
+ the pool id, or a tuple of the form <code>{PoolId, default}</code>, which indicates
+ that this pool will be used as the default pool for the driver.
+ If you don't provide a <code>{PoolId, default}</code> pool option, ErlyDB will use
+the driver-defined default pool id if it exists (you can obtain it by
+calling Mod:get_default_pool_id(), where 'Mod' is the driver's
+module, e.g. 'erlydb_mysql').</p>
+
+ <h5><a name="Options">Options</a></h5>
- <p>Below are some examples:</p>
+ <p>'Options' is a list of options that are used for all modules. This may
+include global driver options as well as options that are passed to
+compile:file/2. For more information, refer to this function's documentation
+in the OTP documentation.</p>
+
+ <h5><a name="IncludePaths">IncludePaths</a></h5>
+
+ <p>Additional include paths that will be used to search for header files
+when compiling the modules.</p>
+
+ <h4><a name="Examples">Examples</a></h4>
<p>Generate code for "musician.erl" using the MySQL driver. Only the default
pool is enabled.</p>
- <pre> code_gen(["musician.erl"], [mysql]).</pre>
+ <pre> code_gen(["musician.erl"], mysql).</pre>
- <p>To use the previous settings but allow unsafe SQL statements, use
-the following:</p>
+ <p>Use the previous settings but allow unsafe SQL statements, and compile
+with debug_info:</p>
- <pre> code_gen(["musician.erl"], [{mysql, [{allow_unsafe_statements, true}]}]).</pre>
+ <pre> code_gen(["musician.erl"],
+ {mysql, [{allow_unsafe_statements, true}]},
+ [debug_info]).</pre>
- <p>Generate code for the modules using the MySQL driver with two additional
-pools, 'pool1' and 'pool2'. The default pool is not overridden.</p>
+ <p>Generate code for the modules using the MySQL driver with two additional
+ pools, 'pool1' and 'pool2'. The default pool is remains <code>erlydb_mysql</code>:</p>
<pre> code_gen(["musician.erl", "instrument.erl"],
- [{mysql, [], [pool1, pool2]}]).</pre>
+ {mysql, [], [pool1, pool2]}).</pre>
+ <p>Similar to the previous setting, but allow unsafe statement and use
+ <code>pool2</code> as the default pool name:</p>
+ <pre> code_gen(["src/musician.erl", "src/instrument.erl"],
+ {mysql, [{allow_unsafe_statements, true}],
+ [{pool1, {pool2, default}}]})</pre>
- <p>tells ErlyDB to use the 'mysql' driver with the default
-code_gen(["src/musician.erl", "src/instrument.erl"],
-[{mysql, [{allow_unsafe_statements, true}],
-[{pool1, {default, pool2}}]}])
-'''</p>
-
- <p>To specify which connection pool ErlyDB should for a specific module, add
-the following line to the module's source code:</p>
+ <p>Generate code for the modules using both the MySQL and Postgres driver.
+The MySQL driver has 2 pools enabled: mysql_pool1 and mysql_pool2, which is
+the default. The Postgres driver has a single default pool, pg_pool1.
+The MySQL driver allows unsafe statements:</p>
- <pre> -erlydb_options(pool_id, PoolId).</pre>
+ <pre> code_gen(["src/musician.erl", "src/instrument.erl", "src/song.erl"],
+ [{mysql, [{allow_unsafe_statements, true}],
+ [{mysql_pool1, {mysql_pool2, default}}]},
+ {psql, [], [{pg_pool1, default}]}])</pre>
- <p>This tells ErlyDB to use the default driver, but a non-default pool id.
-If you want the module to use a non-default driver, use the attribute</p>
+ <h4><a name="Module-Specific_Settings">Module-Specific Settings</a></h4>
- <p>'''
--erlydb_options(driver, Driver).
-'''
-or</p>
+ <p>To specify which connection pool ErlyDB should for a specific module, add
+the following line to the module's source code:</p>
- <p>'''
--erlydb_options(driver, {Driver, PoolId}).
-'''</p>
+ <pre> -erlydb_options([{driver, Driver}, {pool_id, PoolId}]).</pre>
- The first option tells ErlyDB to use a non-default driver with the
- default pool id for the driver. The second option tells ErlyDB
- to use a non-default driver, and a non-default pool id for the driver.
+ The 'driver' option tells ErlyDB to use a non-default driver for the
+ module. The 'pool_id' option tells ErlyDB to use a non-default pool id
+ for the module. Neither option is required -- you can specify only
+ a 'driver' option or only a 'pool_id' option.
</p>
-<h3><a name="code_gen-3">code_gen/3</a></h3>
-<tt>code_gen(Modules, Options, IncludePaths) -> term()
-</tt>
-
<h3><a name="start-1">start/1</a></h3>
<p><tt>start(Driver::atom()) -> ok | {error, Err}</tt></p>
<p>Start an ErlyDB session for the driver using the driver's default
doc/erlydb.html
@@ -84,7 +84,7 @@ that defines the conditions in a {where, Conditions} clause.</p>
fields.</td></tr>
<tr><td valign="top"><a href="#aggregate_related_many_to_many-7">aggregate_related_many_to_many/7</a></td><td>This function works as <a href="#aggregate_related_many_to_one-5"><code>aggregate_related_many_to_one/5</code></a>, but
for modules defining many-to-many relations.</td></tr>
-<tr><td valign="top"><a href="#aggregate_related_many_to_one-6">aggregate_related_many_to_one/6</a></td><td>Get aggregate statistics about fields from related records in
+<tr><td valign="top"><a href="#aggregate_related_many_to_one-7">aggregate_related_many_to_one/7</a></td><td>Get aggregate statistics about fields from related records in
one-to-many relations.</td></tr>
<tr><td valign="top"><a href="#before_delete-1">before_delete/1</a></td><td>A hook that gets called before a record is deleted.</td></tr>
<tr><td valign="top"><a href="#before_save-1">before_save/1</a></td><td>A hook that gets called before a record is saved.</td></tr>
@@ -126,8 +126,8 @@ to the Where and Extras expressions.</td></tr>
according to the Where and Extras expressions.</td></tr>
<tr><td valign="top"><a href="#find_related_many_to_many-5">find_related_many_to_many/5</a></td><td>This function works as <a href="#find_related_many_to_one-4"><code>find_related_many_to_one/4</code></a>, but
for modules defining many-to-many relations.</td></tr>
-<tr><td valign="top"><a href="#find_related_many_to_one-4">find_related_many_to_one/4</a></td><td>Find the set of related records in a one-to-many relation.</td></tr>
-<tr><td valign="top"><a href="#find_related_one_to_many-2">find_related_one_to_many/2</a></td><td>Find the related record for a record from a module having a
+<tr><td valign="top"><a href="#find_related_many_to_one-5">find_related_many_to_one/5</a></td><td>Find the set of related records in a one-to-many relation.</td></tr>
+<tr><td valign="top"><a href="#find_related_one_to_many-3">find_related_one_to_many/3</a></td><td>Find the related record for a record from a module having a
many-to-one relation.</td></tr>
<tr><td valign="top"><a href="#get-2">get/2</a></td><td>A generic getter function ErlyDB uses to generate getters, e.g.</td></tr>
<tr><td valign="top"><a href="#get_module-1">get_module/1</a></td><td>Get the name of the module to which the record belongs.</td></tr>
@@ -159,7 +159,7 @@ property list, e.g.</td></tr>
<tr><td valign="top"><a href="#set_fields_from_strs-3">set_fields_from_strs/3</a></td><td>Equivalent to <a href="#set_fields-4"><tt>set_fields(Module, Record, Fields,
fun field_from_string/2)</tt></a>.
</td></tr>
-<tr><td valign="top"><a href="#set_related_one_to_many-2">set_related_one_to_many/2</a></td><td>Set the foreign key fields of a record from a module having a
+<tr><td valign="top"><a href="#set_related_one_to_many-3">set_related_one_to_many/3</a></td><td>Set the foreign key fields of a record from a module having a
many-to-one relation to the primary key values of the Other record.</td></tr>
<tr><td valign="top"><a href="#table-0">table/0</a></td><td>Return the name of the table that holds the records for this module.</td></tr>
<tr><td valign="top"><a href="#to_iolist-2">to_iolist/2</a></td><td>Equivalent to <a href="#to_iolist-3"><tt>to_iolist(Module, Recs, fun field_to_iolist/2)</tt></a>.
@@ -255,8 +255,8 @@ would generate the following functions:</p>
</p>
<p><b>See also:</b> <a href="#aggregate_related_many_to_one-5">aggregate_related_many_to_one/5</a>.</p>
-<h3><a name="aggregate_related_many_to_one-6">aggregate_related_many_to_one/6</a></h3>
-<p><tt>aggregate_related_many_to_one(OtherModule::atom(), AggFunc::atom(), Rec::<a href="#type-record">record()</a>, Field::atom(), Where::<a href="#type-where_expr">where_expr()</a>, Extras::<a href="#type-extras_expr">extras_expr()</a>) -> float() | integer() | <a href="#type-exit">exit(Err)</a></tt></p>
+<h3><a name="aggregate_related_many_to_one-7">aggregate_related_many_to_one/7</a></h3>
+<p><tt>aggregate_related_many_to_one(OtherModule::atom(), PkFks::term(), AggFunc::atom(), Rec::<a href="#type-record">record()</a>, Field::atom(), Where::<a href="#type-where_expr">where_expr()</a>, Extras::<a href="#type-extras_expr">extras_expr()</a>) -> float() | integer() | <a href="#type-exit">exit(Err)</a></tt></p>
<p><p>Get aggregate statistics about fields from related records in
one-to-many relations.</p>
@@ -583,8 +583,8 @@ according to the Where and Extras expressions.</p>
</p>
<p><b>See also:</b> <a href="#find_related_many_to_one-4">find_related_many_to_one/4</a>.</p>
-<h3><a name="find_related_many_to_one-4">find_related_many_to_one/4</a></h3>
-<p><tt>find_related_many_to_one(OtherModule::atom(), Rec::<a href="#type-record">record()</a>, Where::<a href="#type-where_expr">where_expr()</a>, Extras::<a href="#type-extras_expr">extras_expr()</a>) -> [<a href="#type-record">record()</a>] | <a href="#type-exit">exit(Err)</a></tt></p>
+<h3><a name="find_related_many_to_one-5">find_related_many_to_one/5</a></h3>
+<p><tt>find_related_many_to_one(OtherModule::atom(), PkFks::term(), Rec::<a href="#type-record">record()</a>, Where::<a href="#type-where_expr">where_expr()</a>, Extras::<a href="#type-extras_expr">extras_expr()</a>) -> [<a href="#type-record">record()</a>] | <a href="#type-exit">exit(Err)</a></tt></p>
<p><p>Find the set of related records in a one-to-many relation.</p>
<p>This function isn't meant to be used directly; ErlyDB uses this function
@@ -617,8 +617,8 @@ functions to the 'dog' module:</p>
</p>
<p><b>See also:</b> <a href="#find-3">find/3</a>, <a href="#find_first-3">find_first/3</a>, <a href="#find_max-4">find_max/4</a>, <a href="#find_range-5">find_range/5</a>.</p>
-<h3><a name="find_related_one_to_many-2">find_related_one_to_many/2</a></h3>
-<p><tt>find_related_one_to_many(OtherModule::atom(), Rec::<a href="#type-record">record()</a>) -> <a href="#type-record">record()</a> | <a href="#type-exit">exit(Err)</a></tt></p>
+<h3><a name="find_related_one_to_many-3">find_related_one_to_many/3</a></h3>
+<p><tt>find_related_one_to_many(OtherModule::atom(), PkFkfields::<a href="#type-proplist">proplist()</a>, Rec::<a href="#type-record">record()</a>) -> <a href="#type-record">record()</a> | <a href="#type-exit">exit(Err)</a></tt></p>
<p><p>Find the related record for a record from a module having a
many-to-one relation.</p>
@@ -835,8 +835,8 @@ value.</p>
<p><b>See also:</b> <a href="#field_from_string-2">field_from_string/2</a>.</p>
-<h3><a name="set_related_one_to_many-2">set_related_one_to_many/2</a></h3>
-<p><tt>set_related_one_to_many(Rec::<a href="#type-record">record()</a>, Other::<a href="#type-record">record()</a>) -> <a href="#type-record">record()</a> | <a href="#type-exit">exit(Err)</a></tt></p>
+<h3><a name="set_related_one_to_many-3">set_related_one_to_many/3</a></h3>
+<p><tt>set_related_one_to_many(Rec::<a href="#type-record">record()</a>, PkFkFields::<a href="#type-proplist">proplist()</a>, Other::<a href="#type-record">record()</a>) -> <a href="#type-record">record()</a> | <a href="#type-exit">exit(Err)</a></tt></p>
<p><p>Set the foreign key fields of a record from a module having a
many-to-one relation to the primary key values of the Other record.</p>
doc/erlydb_base.html
@@ -42,6 +42,7 @@ This module implements the MySQL driver for ErlyDB.
<table width="100%" border="1"><tr><td valign="top"><a href="#connect-5">connect/5</a></td><td>Call connect/7 with Port set to 3306 and Reconnect set to 'true'.</td></tr>
<tr><td valign="top"><a href="#connect-7">connect/7</a></td><td>Add a connection to the connection pool.</td></tr>
<tr><td valign="top"><a href="#connect-8">connect/8</a></td><td>Add a connection to the connection pool, with encoding specified.</td></tr>
+<tr><td valign="top"><a href="#connect-9">connect/9</a></td><td>Add a connection to the connection pool, with encoding specified.</td></tr>
<tr><td valign="top"><a href="#execute-2">execute/2</a></td><td>Execute a statement that was previously prepared with
prepare/2.</td></tr>
<tr><td valign="top"><a href="#execute-3">execute/3</a></td><td>Execute a prepared statement with the list of parameters.</td></tr>
@@ -53,7 +54,7 @@ This module implements the MySQL driver for ErlyDB.
update() function.</td></tr>
<tr><td valign="top"><a href="#execute_update-3">execute_update/3</a></td><td>Execute a prepared statement with the list of parameters and
and return the result as the the update() function.</td></tr>
-<tr><td valign="top"><a href="#get_default_pool_name-0">get_default_pool_name/0</a></td><td>Get the default connection pool name for the driver.</td></tr>
+<tr><td valign="top"><a href="#get_default_pool_id-0">get_default_pool_id/0</a></td><td>Get the default connection pool name for the driver.</td></tr>
<tr><td valign="top"><a href="#get_last_insert_id-2">get_last_insert_id/2</a></td><td>Get the id of the last inserted record.</td></tr>
<tr><td valign="top"><a href="#get_metadata-1">get_metadata/1</a></td><td>Get the table names and fields for the database.</td></tr>
<tr><td valign="top"><a href="#prepare-2">prepare/2</a></td><td>Register a prepared statement with the MySQL dispatcher.</td></tr>
@@ -78,17 +79,28 @@ This module implements the MySQL driver for ErlyDB.
<h3><a name="connect-5">connect/5</a></h3>
<p><tt>connect(PoolId::atom(), Hostname::string(), Username::string(), Password::string(), Database::string()) -> ok</tt></p>
<p>Call connect/7 with Port set to 3306 and Reconnect set to 'true'.
+ If the connection is lost, reconnection is attempted.
+ The connection process is linked to the calling process.
</p>
<h3><a name="connect-7">connect/7</a></h3>
<p><tt>connect(PoolId::atom(), Hostname::string, Port::integer(), Username::string(), Password::string(), Database::string(), Reconnect::<a href="#type-boolean">boolean()</a>) -> ok</tt></p>
<p>Add a connection to the connection pool. If PoolId is
- 'undefined', the default pool, 'erlydb_mysql', is used.
+ 'undefined', the default pool, 'erlydb_mysql', is used. The connection
+ process is linked to the calling process.
</p>
<h3><a name="connect-8">connect/8</a></h3>
<p><tt>connect(PoolId::atom(), Hostname::string, Port::integer(), Username::string(), Password::string(), Database::string(), Encoding, Reconnect::<a href="#type-boolean">boolean()</a>) -> ok</tt></p>
<p>Add a connection to the connection pool, with encoding specified.
+ The connection process is linked to the calling process.
+ </p>
+
+<h3><a name="connect-9">connect/9</a></h3>
+<p><tt>connect(PoolId::atom(), Hostname::string, Port::integer(), Username::string(), Password::string(), Database::string(), Encoding::string(), Reconnect::<a href="#type-boolean">boolean()</a>, LinkConnection::bool()) -> ok</tt></p>
+<p>Add a connection to the connection pool, with encoding specified.
+ If LinkConnection == false, the connection will not be linked to the
+ current process.
</p>
<h3><a name="execute-2">execute/2</a></h3>
@@ -126,8 +138,8 @@ This module implements the MySQL driver for ErlyDB.
and return the result as the the update() function.
</p>
-<h3><a name="get_default_pool_name-0">get_default_pool_name/0</a></h3>
-<p><tt>get_default_pool_name() -> atom()</tt></p>
+<h3><a name="get_default_pool_id-0">get_default_pool_id/0</a></h3>
+<p><tt>get_default_pool_id() -> atom()</tt></p>
<p>Get the default connection pool name for the driver.
</p>
doc/erlydb_mysql.html
@@ -36,6 +36,9 @@ that implements basic CRUD features for a database table.</td></tr>
<tr><td valign="top"><a href="#get_initial_ewc-1">get_initial_ewc/1</a></td><td>Get the expanded 'ewc' tuple for the request.</td></tr>
<tr><td valign="top"><a href="#out-1">out/1</a></td><td>This is the out/1 function that Yaws calls when passing
HTTP requests to the ErlyWeb appmod.</td></tr>
+<tr><td valign="top"><a href="#out-2">out/2</a></td><td>This function is useful for embedding the result of a 'phased'
+ErlyWeb rendering in an ErlyWeb component from the same application,
+but using a different app controller.</td></tr>
</table>
<h2><a name="functions">Function Details</a></h2>
@@ -61,7 +64,10 @@ extension are compiled with ErlTL.</p>
ErlyWeb also lets you define the following options:</p>
<p>- <code>{last_compile_time, LocalTime}</code>: Tells ErlyWeb to not compile files
-that haven't changed since LocalTime.</p>
+that haven't changed since LocalTime.
+Since ErlyWeb 0.7, you can use 'auto' for LocalTime. This
+instructs ErlyWeb to compile only the files that have changed since
+the last compilation. This is the recommended option.</p>
<p>- <code>{erlydb_driver, Name}</code>: Tells ErlyWeb which ErlyDB driver to use
when calling erlydb:code_gen on models that are placed in src/components.
@@ -180,5 +186,20 @@ logic for handling client requests for different components.</p>
<p>This is the out/1 function that Yaws calls when passing
HTTP requests to the ErlyWeb appmod.
</p>
+
+<h3><a name="out-2">out/2</a></h3>
+<p><tt>out(A::<a href="#type-arg">arg()</a>, AppController::atom()) -> term()</tt></p>
+<p><p>This function is useful for embedding the result of a 'phased'
+ErlyWeb rendering in an ErlyWeb component from the same application,
+but using a different app controller.</p>
+
+ This function was originally designed to simplify Facebook app development
+ with ErlyWeb using Erlang2Facebook
+ (http://code.google.com/p/erlang2facebook).
+ In erlang2facebook, the fb_canvas component intercepts requests
+ from Facebook and authenticates them. After authentication, it may be
+ useful to start a new ErlyWeb "flow" using an alternative app controller
+ and display the result in of this flow the output of fb_canvas.
+ </p>
</body>
</html>
doc/erlyweb.html
@@ -234,28 +234,20 @@ component name as parameters.</p>
<pre>http://my-cool-app.com/people/bob</pre>
<p>ErlyWeb by default would try to invoke the function 'bob/1' in
-people_controller. This is probably not what you want. Instead, you
-probably want "bob" to be a parameter to a single generic function in
-people_controller. You can accomplish this by implementing the
-'people' component as follows:</p>
+people_controller. You can tell ErlyWeb to override this behavior and instead
+pass "bob" as a parameter to people_controller:catch_all/2 as follows:</p>
<p>people_controller.erl:</p>
<pre>-module(people_controller).
-export(index/1, catch_all/2).
-index(_A) ->
- {data, undefined}.
-
catch_all(A, [Name]) ->
{data, Name}.</pre>
<p>people_view.et:</p>
-<pre><%@ index(_) %>
-nothing much here
-
-<%@ catch_all(Name) %>
+<pre><%@ catch_all(Name) %>
<% Name %>'s homepage
...</pre>
@@ -299,12 +291,12 @@ such HTTP headers common to some or all of a controller's functions.</p>
<h5><a name="after_render/3">after_render/3</a></h5>
<p>ErlyWeb lets you implement the after_render/3 hook in controllers to get
-access to the rendered output. Teh </p>
+access to the rendered output.</p>
<p>The signature of after_render/2 is</p>
<pre>after_render(FuncName::atom(), Params::[term()], Rendered::iolist()) ->
- Ignored::any().</pre>
+ Ignored::term().</pre>
<p>You can use the after_render/3 hook to implement a granular caching system.</p>
@@ -391,26 +383,25 @@ index(A) ->
home_view.et:
<pre><% index(Album) %>
Your favorite album is:<br/>
-<% Album %>
+<% Album %></pre>
-== The App Controller ==
+<h3><a name="The_App_Controller">The App Controller</a></h3>
-ErlyWeb applications have a module called [AppName]_app_controller,
+<p>ErlyWeb applications have a module called [AppName]_app_controller,
whose source file is in the 'src' directory by convention. The app controller
provides the entry-point into ErlyWeb applications via the hook/1 function.
Starting from ErlyWeb 0.6, the app controller can also have an error-trapping,
-error/3.
+error/3.</p>
-=== hook/1 ===
+<h4><a name="hook/1">hook/1</a></h4>
-The signature for hook/1 is
+<p>The signature for hook/1 is</p>
-```
-hook(A::arg()) -> hook_result() | [hook_result()]
+<pre>hook(A::arg()) -> hook_result() | [hook_result()]
hook_result = ewc() | yaws_term() | response() |
{phased, Ewc::ewc() | Response::response(),
- fun(ExpandedEwc::ewc(), Data::iolist()) ->
+ fun(ExpandedEwc::ewc(), Data::iolist(), PhasedVars::proplist()) ->
FinalEwc::ewc()}
ewc() = any `ewc' tuple
@@ -436,39 +427,100 @@ top-level components. If you return a different <code>ewc</code> tuple (e.g. one
returned by calling <a href="erlyweb.html#get_initial_ewc-1"><code>erlyweb:get_initial_ewc/1</code></a>), ErlyWeb expects you
to ensure the safety of your components manually.</p>
-<p>In ErlyWeb 0.5, the <code>phased</code> return type was introduced to faciliate
-the conditional embedding of any rendered data in containers
-(before ErlyWeb 0.5, a similar, but weaker functionality was provided by
+<h4><a name="Phased_Rendering">Phased Rendering</a></h4>
+
+<p>In ErlyWeb 0.5, the <code>phased</code> return type for hook/1 was introduced to let you
+embed components in containers after those components are rendered
+but before they are sent to the browser
+(before ErlyWeb 0.5, a similar but weaker functionality was provided by
app views, which ErlyWeb no longer supports). By returning
-<code>{phased, Ewc, Fun}</code>, you are instructing ErlyWeb to first render the
+<code>{phased, Ewc, Fun}</code>, you instruct ErlyWeb to first render the
requested component, and if the result includes a rendered
iolist (i.e., the requested component didn't return only headers),
-then nest the resulting iolist in a container before returning it.</p>
+then pass it to the function Fun, which would decide if/how the iolist should
+be embedded in a container.</p>
+
+<p>The reason this is feature called 'phased' rendering is that ErlyWeb renders
+the response in 2 phases: first, the requested component, and second, the
+container in which the component should be embedded.</p>
+
+<p>Fun takes 3 parameters: the fully expanded 'ewc' tuple
+that ErlyWeb has rendered (this is usually the result of calling
+erlyweb:get_initial_ewc({ewc, A})), the rendered
+iolist, and an opaque parameter called 'PhasedVars' ('PhasedVars' was
+introduced in ErlyWeb 0.7). PhasedVars is a list of values returned from
+the rendered controller function, in a special tuple of the type
+{phased_vars, Vars}. The purpose of 'PhasedVars' is to let the controller
+function pass arbitrary values to the component that
+is rendered in the second phase. It is useful, for example, for letting
+the controller function set the title of a page when the page's header
+is rendered by the container in the second rendering phase.</p>
-<p>This approach is superior to directly embedding the requested component in a
-container because it allows the requested component to return headers
-(sub-components aren't allowed to return the <code>{response, Elems}</code> tuple,
-as discussed above). In addition, this approach lets ErlyWeb skip the
-unnecessary rendering of the container when the requested component
-returns only headers.</p>
+<p>Fun may return any 'ewc' or 'data' tuple. ErlyWeb takes the result of Fun,
+renders it, and send the result back to the browser.</p>
-<p>Consider this trivial example: returning</p>
+<p>Consider this example return value from hook/1:</p>
-<pre>{phased, {ewc, A}, fun(_Ewc, Data) -> {data, Data} end}</pre>
+<pre>{phased, {ewc, A}, fun(_Ewc, Data, _PhasedVars) -> {data, Data} end}</pre>
-<p>is tantamount to returning</p>
+<p>It is tantamount to returning</p>
<pre>{ewc, A}</pre>
-<p>Another example: the return value below</p>
+<p>This return value tells ErlyWeb to render the component
+that corresponds to the arg's appmoddata field, and then return
+the rendered iolist to the browser verbatim.</p>
+
+<p>Below is a more advanced example.</p>
<pre>{phased, {ewc, A},
- fun(_Ewc, Data) ->
- {html_container, index, [A, {data, Data}]}
+ fun(_Ewc, Data, PhasedVars) ->
+ {html_container,
+ [A, {data, Data}, proplists:get_value(title, PhasedVars)]}
end}</pre>
-<p>tells ErlyWeb to embed any rendered data in html_container by passing
-the parameters <code>[A, {data, Data}]</code> to its 'index' function.</p>
+<p>This return value tells ErlyWeb to first render the component that corresponds
+to the arg's appmoddata field, and then embed the rendered iolist
+(the 'Data' variable) in html_container. After ErlyWeb renders
+the requested component, it calls
+<code>html_container_controller:index(A, {data, Data}, proplists:get_value(title, PhasedVars))</code> and passes the result to html_container_view:index/1.</p>
+
+<p>How do you set the value of the 'title' property in PhasedVars? Below is
+an example controller function for an 'album' component that fetches from
+the database an album and its related songs, passes the song names to the
+view function, and sets the page's title according to the album name.</p>
+
+<p>album_controller.erl:</p>
+
+<pre>show(A, Id) ->
+ Album = album:find_id(Id),
+ AlbumName = album:name(Album),
+ Songs = album:songs(Album),
+ {response,
+ [{phased_vars, [{title, [<<"song list for ">>, AlbumName]}]},
+ {body, {data, [{song:name(S) || S <- Songs}]}}]}.</pre>
+
+<p>Finally, below is an example html_container that takes the iolist and the
+'title' parameter and inserts them into the proper positions in the HTML
+page.</p>
+
+<p>html_container_controller.erl:</p>
+
+<pre>index(A, Ewc, Title) ->
+ [Ewc, {data, Title}].</pre>
+
+<p>html_container_view.et:</p>
+
+<pre><%@ index([Data, Title]) %>
+<html>
+<head>
+<title><% Title %></title>
+</head>
+<body>
+<% Data %>
+</body>
+</html></pre>
+
<h4><a name="error/3">error/3</a></h4>
doc/overview-summary.html
@@ -231,10 +231,8 @@ http://my-cool-app.com/people/bob
'''
ErlyWeb by default would try to invoke the function 'bob/1' in
-people_controller. This is probably not what you want. Instead, you
-probably want "bob" to be a parameter to a single generic function in
-people_controller. You can accomplish this by implementing the
-'people' component as follows:
+people_controller. You can tell ErlyWeb to override this behavior and instead
+pass "bob" as a parameter to people_controller:catch_all/2 as follows:
people_controller.erl:
@@ -242,9 +240,6 @@ people_controller.erl:
-module(people_controller).
-export(index/1, catch_all/2).
-index(_A) ->
- {data, undefined}.
-
catch_all(A, [Name]) ->
{data, Name}.
'''
@@ -252,9 +247,6 @@ catch_all(A, [Name]) ->
people_view.et:
```
-<%@ index(_) %>
-nothing much here
-
<%@ catch_all(Name) %>
<% Name %>'s homepage
...
@@ -414,6 +406,7 @@ home_view.et:
<% index(Album) %>
Your favorite album is:<br/>
<% Album %>
+'''
== The App Controller ==
@@ -432,7 +425,7 @@ hook(A::arg()) -> hook_result() | [hook_result()]
hook_result = ewc() | yaws_term() | response() |
{phased, Ewc::ewc() | Response::response(),
- fun(ExpandedEwc::ewc(), Data::iolist()) ->
+ fun(ExpandedEwc::ewc(), Data::iolist(), PhasedVars::proplist()) ->
FinalEwc::ewc()}
ewc() = any `ewc' tuple
@@ -461,45 +454,112 @@ top-level components. If you return a different `ewc' tuple (e.g. one
returned by calling {@link erlyweb:get_initial_ewc/1}), ErlyWeb expects you
to ensure the safety of your components manually.
-In ErlyWeb 0.5, the `phased' return type was introduced to faciliate
-the conditional embedding of any rendered data in containers
-(before ErlyWeb 0.5, a similar, but weaker functionality was provided by
+=== Phased Rendering ===
+
+In ErlyWeb 0.5, the `phased' return type for hook/1 was introduced to let you
+embed components in containers after those components are rendered
+but before they are sent to the browser
+(before ErlyWeb 0.5, a similar but weaker functionality was provided by
app views, which ErlyWeb no longer supports). By returning
-`{phased, Ewc, Fun}', you are instructing ErlyWeb to first render the
+`{phased, Ewc, Fun}', you instruct ErlyWeb to first render the
requested component, and if the result includes a rendered
iolist (i.e., the requested component didn't return only headers),
-then nest the resulting iolist in a container before returning it.
-
-This approach is superior to directly embedding the requested component in a
-container because it allows the requested component to return headers
-(sub-components aren't allowed to return the `{response, Elems}' tuple,
-as discussed above). In addition, this approach lets ErlyWeb skip the
-unnecessary rendering of the container when the requested component
-returns only headers.
-
-Consider this trivial example: returning
+then pass it to the function Fun, which would decide if/how the iolist should
+be embedded in a container.
+
+The reason this is feature called 'phased' rendering is that ErlyWeb renders
+the response in 2 phases: first, the requested component, and second, the
+container in which the component should be embedded.
+
+Fun takes 3 parameters: the fully expanded 'ewc' tuple
+that ErlyWeb has rendered (this is usually the result of calling
+erlyweb:get_initial_ewc({ewc, A})), the rendered
+iolist, and an opaque parameter called 'PhasedVars' ('PhasedVars' was
+introduced in ErlyWeb 0.7). PhasedVars is a list of values returned from
+the rendered controller function, in a special tuple of the type
+{phased_vars, Vars}. The purpose of 'PhasedVars' is to let the controller
+function pass arbitrary values to the component that
+is rendered in the second phase. It is useful, for example, for letting
+the controller function set the title of a page when the page's header
+is rendered by the container in the second rendering phase.
+
+Fun may return any 'ewc' or 'data' tuple. ErlyWeb takes the result of Fun,
+renders it, and send the result back to the browser.
+
+Consider this example return value from hook/1:
```
-{phased, {ewc, A}, fun(_Ewc, Data) -> {data, Data} end}
+{phased, {ewc, A}, fun(_Ewc, Data, _PhasedVars) -> {data, Data} end}
'''
-is tantamount to returning
+It is tantamount to returning
```
{ewc, A}
'''
-Another example: the return value below
+This return value tells ErlyWeb to render the component
+that corresponds to the arg's appmoddata field, and then return
+the rendered iolist to the browser verbatim.
+
+Below is a more advanced example.
```
{phased, {ewc, A},
- fun(_Ewc, Data) ->
- {html_container, index, [A, {data, Data}]}
+ fun(_Ewc, Data, PhasedVars) ->
+ {html_container,
+ [A, {data, Data}, proplists:get_value(title, PhasedVars)]}
end}
'''
-tells ErlyWeb to embed any rendered data in html_container by passing
-the parameters `[A, {data, Data}]' to its 'index' function.
+This return value tells ErlyWeb to first render the component that corresponds
+to the arg's appmoddata field, and then embed the rendered iolist
+(the 'Data' variable) in html_container. After ErlyWeb renders
+the requested component, it calls
+`html_container_controller:index(A, {data, Data}, proplists:get_value(title, PhasedVars))' and passes the result to html_container_view:index/1.
+
+How do you set the value of the 'title' property in PhasedVars? Below is
+an example controller function for an 'album' component that fetches from
+the database an album and its related songs, passes the song names to the
+view function, and sets the page's title according to the album name.
+
+album_controller.erl:
+
+```
+show(A, Id) ->
+ Album = album:find_id(Id),
+ AlbumName = album:name(Album),
+ Songs = album:songs(Album),
+ {response,
+ [{phased_vars, [{title, [<<"song list for ">>, AlbumName]}]},
+ {body, {data, [{song:name(S) || S <- Songs}]}}]}.
+'''
+
+Finally, below is an example html_container that takes the iolist and the
+'title' parameter and inserts them into the proper positions in the HTML
+page.
+
+html_container_controller.erl:
+
+```
+index(A, Ewc, Title) ->
+ [Ewc, {data, Title}].
+'''
+
+html_container_view.et:
+
+```
+<%@ index([Data, Title]) %>
+<html>
+<head>
+<title><% Title %></title>
+</head>
+<body>
+<% Data %>
+</body>
+</html>
+'''
+
=== error/3 ===
doc/overview.edoc
@@ -28,7 +28,10 @@ having to include yaws_api.hrl.</p>
with the modified value.
<h2><a name="index">Function Index</a></h2>
-<table width="100%" border="1"><tr><td valign="top"><a href="#appmod_prepath-1">appmod_prepath/1</a></td><td/></tr>
+<table width="100%" border="1"><tr><td valign="top"><a href="#add_all_to_opaque-2">add_all_to_opaque/2</a></td><td>applies add_to_opaque for all values in the list.</td></tr>
+<tr><td valign="top"><a href="#add_to_opaque-2">add_to_opaque/2</a></td><td>Equivalent to <tt>Arg#arg{opaque = [Val | A#arg.opaque]}</tt>.
+</td></tr>
+<tr><td valign="top"><a href="#appmod_prepath-1">appmod_prepath/1</a></td><td/></tr>
<tr><td valign="top"><a href="#appmod_prepath-2">appmod_prepath/2</a></td><td/></tr>
<tr><td valign="top"><a href="#appmoddata-1">appmoddata/1</a></td><td/></tr>
<tr><td valign="top"><a href="#appmoddata-2">appmoddata/2</a></td><td/></tr>
@@ -44,6 +47,7 @@ having to include yaws_api.hrl.</p>
<tr><td valign="top"><a href="#docroot-2">docroot/2</a></td><td/></tr>
<tr><td valign="top"><a href="#fullpath-1">fullpath/1</a></td><td/></tr>
<tr><td valign="top"><a href="#fullpath-2">fullpath/2</a></td><td/></tr>
+<tr><td valign="top"><a href="#get_opaque_val-2">get_opaque_val/2</a></td><td>Return the value corrsponding to the Key in the opaque proplist.</td></tr>
<tr><td valign="top"><a href="#headers-1">headers/1</a></td><td/></tr>
<tr><td valign="top"><a href="#headers-2">headers/2</a></td><td/></tr>
<tr><td valign="top"><a href="#method-1">method/1</a></td><td/></tr>
@@ -66,6 +70,16 @@ having to include yaws_api.hrl.</p>
<h2><a name="functions">Function Details</a></h2>
+<h3><a name="add_all_to_opaque-2">add_all_to_opaque/2</a></h3>
+<p><tt>add_all_to_opaque(A::<a href="#type-arg">arg()</a>, Vals::[term()]) -> <a href="#type-arg">arg()</a></tt></p>
+<p>applies add_to_opaque for all values in the list
+ </p>
+
+<h3><a name="add_to_opaque-2">add_to_opaque/2</a></h3>
+<tt>add_to_opaque(Arg, Val) -> term()
+</tt><p>Equivalent to <tt>Arg#arg{opaque = [Val | A#arg.opaque]}</tt>.</p>
+
+
<h3><a name="appmod_prepath-1">appmod_prepath/1</a></h3>
<tt>appmod_prepath(Arg) -> term()
</tt>
@@ -130,6 +144,12 @@ having to include yaws_api.hrl.</p>
<tt>fullpath(Arg, Val) -> term()
</tt>
+<h3><a name="get_opaque_val-2">get_opaque_val/2</a></h3>
+<p><tt>get_opaque_val(A::<a href="#type-arg">arg()</a>, Key::term()) -> term() | undefined</tt></p>
+<p>Return the value corrsponding to the Key in the opaque proplist.
+ If the key isn't found, return 'undefined'.
+ </p>
+
<h3><a name="headers-1">headers/1</a></h3>
<tt>headers(Arg) -> term()
</tt>
doc/yaws_arg.html
@@ -141,11 +141,11 @@ driver_mod(mnesia) -> erlydb_mnesia;
driver_mod(odbc) -> erlydb_odbc.
-%% @equiv code_gen(Modules, Drivers, []).
+%% @equiv code_gen(Modules, Drivers, [])
code_gen(Modules, Drivers) ->
code_gen(Modules, Drivers, []).
-%% @equiv code_gen(Modules, Drivers, Options, []).
+%% @equiv code_gen(Modules, Drivers, Options, [])
code_gen(Modules, Drivers, Options) ->
code_gen(Modules, Drivers, Options, []).
src/erlydb/erlydb.erl
@@ -1104,7 +1104,9 @@ find_related_one_to_many(OtherModule, PkFkFields, Rec) ->
%% @see find_first/3
%% @see find_max/4
%% @see find_range/5
-%% @spec find_related_many_to_one(OtherModule::atom(), Rec::record(),
+%% @spec find_related_many_to_one(OtherModule::atom(),
+%% PkFks::term(),
+%% Rec::record(),
%% Where::where_expr(), Extras::extras_expr()) -> [record()] | exit(Err)
find_related_many_to_one(OtherModule, PkFks, Rec, Where,
Extras) ->
@@ -1135,7 +1137,9 @@ find_related_many_to_one(OtherModule, PkFks, Rec, Where,
%% {@link aggregate/5}.
%%
%% @see aggregate/5
-%% @spec aggregate_related_many_to_one(OtherModule::atom(), AggFunc::atom(),
+%% @spec aggregate_related_many_to_one(OtherModule::atom(),
+%% PkFks::term(),
+%% AggFunc::atom(),
%% Rec::record(), Field::atom(),
%% Where::where_expr(), Extras::extras_expr()) -> float() | integer() |
%% exit(Err)
src/erlydb/erlydb_base.erl
@@ -204,7 +204,7 @@ get_metadata(Options) ->
%% @doc Get the default connection pool name for the driver.
%%
-%% @spec get_default_pool_name() -> atom()
+%% @spec get_default_pool_id() -> atom()
get_default_pool_id() ->
?Epid.
src/erlydb/erlydb_mysql.erl
@@ -35,13 +35,13 @@
new() ->
#arg{}.
-%% @equiv Arg#arg{opaque = [Val | A#arg.opaque]}.
+%% @equiv Arg#arg{opaque = [Val | A#arg.opaque]}
add_to_opaque(Arg, Val) ->
Arg#arg{opaque = [Val | Arg#arg.opaque]}.
%% @doc applies add_to_opaque for all values in the list
%%
-%% @spec add_all_to_opaque(A::arg(), Vals::[term()])
+%% @spec add_all_to_opaque(A::arg(), Vals::[term()]) -> arg()
add_all_to_opaque(A, Vals) ->
lists:foldl(
fun(Val, A1) ->
src/erlyweb/yaws_arg.erl
fa189eabc057ff04da4091cea185fa32b77331c0
yarivvv
yarivvv
http://github.com/yariv/erlyweb/commit/c948d5214797bfb56cc42d2f8c9b3258ce29876d
c948d5214797bfb56cc42d2f8c9b3258ce29876d
2007-12-25T01:34:26-08:00
2007-12-25T01:34:26-08:00
documentation changes
d7d7ca6c28d750d6deea941e85f3ff6517a2e57f
yarivvv
yarivvv