Skip to content
Browse files

Merge pull request #7 from hmobius/master

Added new naming conventions section
  • Loading branch information...
2 parents acbb51b + 2fb68a0 commit 6ac018f8950484b812b7ea0baaf048234396bc0b @hmobius hmobius committed Apr 20, 2012
View
BIN images/NamingConventions01.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN images/NamingConventions02.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
1 index.html
@@ -1 +1,2 @@
SimpleFX holding page
+<a href="simpledata/docs/index.html">Docs</a>
View
8 simpledata/docs/content/01 Getting Started/01 What is Simple.Data.html
@@ -8,15 +8,15 @@
<p>Simple.Data is a lightweight framework that uses the dynamic features of .NET 4 to provide an expressive, ORM-ish way of accessing and manipulating data without any of the code pre-generation and boilerplate required by other frameworks. Instead, it interprets method and property names at runtime and maps them to your underlying data-store using a convention-based approach. It does not permit SQL Injection. It was built by Mark Rendle <a href="http://blog.markrendle.net/2010/08/05/introducing-simple-data/">in reaction to Microsoft&#8217;s release of Microsoft.Data.dll</a>, taking Ruby&#8217;s <a href="http://ar.rubyonrails.org/">ActiveRecord</a> and <a href="http://datamapper.org/">DataMapper</a> gems as its inspiration.</p>
<blockquote>&#8220;It&#8217;s not an O/RM. It looks a bit like one, but it doesn&#8217;t need objects, it doesn&#8217;t need a relational database, and it doesn&#8217;t need any mapping configuration. So it&#8217;s an O/RM without the O or the R or the M. So it&#8217;s just a /.&#8221;</blockquote>
<p>Let&#8217;s take an example</p>
-<pre class="brush:csharp">public Album FindAlbumByTitle(string title)
+<pre class="brush:csharp">public Album FindAlbumsByTitle(string title)
{
- return Database.Open().Albums.FindByTitle(title);
+ return Database.Open().Albums.FindAllByTitle(title);
}</pre>
<p>In this example,</p>
<ul>
<li><code class="method">Database.Open()</code> is dynamic and has no pre-defined <code class="property">Albums</code> property.</li>
- <li><code class="property">Albums</code> is returned as a <code class="type">DynamicTable</code>, which is also dynamic. It has no pre-defined <code class="method">FindByTitle()</code> method.</li>
- <li>When Simple.Data sees a call to a <code class="method">FindBy*()</code> method, it pulls apart the rest of the method name, combines it with the arguments and builds an ADO.NET command which safely encapsulates the name and password values inside parameters.</li>
+ <li><code class="property">Albums</code> is returned as a <code class="type">DynamicTable</code>, which is also dynamic. It has no pre-defined <code class="method">FindAllByTitle()</code> method.</li>
+ <li>When Simple.Data sees a call to a <code class="method">FindAllBy*()</code> method, it pulls apart the rest of the method name, combines it with the arguments and builds an ADO.NET command which safely encapsulates the name and password values inside parameters.</li>
</ul>
<p>Assuming you&#8217;re using Simple.Data to access a SQL-based database, the following SQL (or similar depending on your database) is generated along with the requisite boilerplate code to send it to the database and retrieve the resulting data.</p>
<pre class="brush:sql">SELECT * FROM Albums WHERE Title = @p1</pre>
View
71 simpledata/docs/content/02 Basics/00 Naming Conventions.html
@@ -0,0 +1,71 @@
+<!DOCTYPE HTML>
+<html lang="en">
+<head>
+ <title>Naming Conventions</title>
+</head>
+<body>
+ <h2>Naming Conventions</h2>
+ <p>One of the great features of Simple.Data is that it interprets method and property names at runtime and maps them to your underlying data-store using a convention-based approach.</p>
+<p><img src="../../images/NamingConventions01.png" alt=""/></p>
+<p>The convention is as follows.</p>
+<ol>
+ <li>
+ <p>All method calls start with a reference to the database which you generate by calling one of the four <code class="method">Database.Open()</code> methods.</p>
+ </li>
+ <li>
+ <p>The primary table or view in your query is specified next. When the database is eventually queried for data (Simple.Data is late-binding by default), it first checks to see if the given name exists as either a table or a view. If it doesn&#8217;t, it checks to see whether the given name is singular or plural and then checks whether the plural or singular form of the word is the correct name instead. </p>
+ <p>In the example above, the name of the table targeted is actually <code class="value">Album</code> rather than <code class="value">Albums</code>. Simple.Data first retrieves a list of tables and views from the <code class="value">INFORMATION_SCHEMA.TABLES</code> system table and attempts to find the target name within them.</p>
+ <ol>
+ <li>
+ <p>It tries an exact match first (Albums)</p>
+ </li>
+ <li>
+ <p>Then it tries a case-insensitive match (albums)</p>
+ </li>
+ <li>
+ <p>Then a pluralized version if the string &#8216;is not a plural&#8217; (Albums)</p>
+ </li>
+ <li>
+ <p>Finally a singularized version if the string &#8216;is a plural&#8217; (Album)</p>
+ </li>
+</ol>
+<p>You can also specify a database schema to identify the correct table or view. For example, <code class="value">Album</code> is a table in the <code class="value">dbo</code> schema.</p>
+<pre class="brush:csharp">db.dbo.Albums.FindByGenreId(1);</pre>
+<p>The general form of this syntax is</p>
+<pre class="brush:csharp">DatabaseReference.[schema_name.]Table_or_View.method();</pre>
+ </li>
+ <li>
+ <p>Simple.Data contains twenty methods for data retrieval and manipulation (see list here). One of those methods is specified next.</p>
+ </li>
+ <li>
+ <p>If you choose to use one of the eight methods ending in “By”, for example FindBy(), you must also specify at least one column in the primary table or view by which to filter your search along with a value for it. For example,</p>
+ <pre class="brush:csharp">db.Albums.FindByGenreId(1);</pre>
+ <p>will resolve into a query searching for all rows in the Album table where GenreId is set to 1.</p>
+ <p>Additional criteria can be added by concatenating more column names to the end of the method name, separated by “And”, with the column values set in the arguments to the method. For example,</p>
+ <pre class="brush:csharp">db.Albums.FindByGenreIdAndArtistId(1,1);</pre>
+<p><img src="../../images/NamingConventions02.png" alt=""/></p>
+<p>Note that Simple.Data will also attempt to resolve names by removing all characters except for alpha-numerics and underscores from object names, and forcing all names to lower case.
+ So, for example, <code class="value">Albums.GenreId</code> will match all of:</p>
+<ul>
+ <li>Albums.GenreId</li>
+ <li>Album.GenreId</li>
+ <li>ALBUMS.GENREID</li>
+ <li>ALBUM.GENREID</li>
+ <li>[ALBUMS].[GENREID]</li>
+ <li>[ALBUM].[GENREID]</li>
+</ul>
+<p>And other such variations.</p>
+ </li>
+</ol>
+
+
+
+
+
+
+
+
+
+
+</body>
+</html>
View
0 ...cs/content/02 Finding Data/01 FindBy.html → ...ata/docs/content/02 Basics/01 FindBy.html
File renamed without changes.
View
0 ...content/02 Finding Data/02 FindAllBy.html → .../docs/content/02 Basics/02 FindAllBy.html
File renamed without changes.
View
0 .../02 Finding Data/03 Find and FindAll.html → ...ontent/02 Basics/03 Find and FindAll.html
File renamed without changes.
View
18 simpledata/docs/content/02 Basics/index.html
@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <title>Basics</title>
+</head>
+<body>
+<h2>The Basics</h2>
+<p>In this section, we look at how you use Simple.Data to perform basic data operations</p>
+<ul>
+ <li>Data Retrieval</li>
+ <li>Adding new data</li>
+ <li>Updating existing data</li>
+ <li>&#8216;Upsert&#8217;ing new and existing data at the same time</li>
+ <li>Deleting data</li>
+</ul>
+<p>We also take a quick look at some useful helper functions in the Simple.Data API</p>
+</body>
+</html>
View
9 simpledata/docs/content/02 Finding Data/index.html
@@ -1,9 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
- <title></title>
-</head>
-<body>
-<h2>Finding Data</h2>
-</body>
-</html>

0 comments on commit 6ac018f

Please sign in to comment.
Something went wrong with that request. Please try again.