FileSystem Location

Your custom blocks should be stored under the RockWeb\Plugins folder in a sub folder for your organization/domain.

Put your javascripts in a Scripts folder and your CSS stylesheets in a Styles folder as depicted here:

RockWeb
\---Plugins
    \---org_rocksolidchurch
        +---MyProject
        |   |   WidgetBlock.ascx
        |   |
        |   +---Assets
        |   +---Scripts
        |   |       widget.js
        |   |
        |   \---Styles
        |           widget.css
        |
        +---Scripts
        \---Styles
                myshared.css

You can share your common styles and scripts across all your projects by putting them into a Styles and Scripts folder at your domain root folder. However, you will probably want to keep things simple since it could affect the dependencies and complexity of packaging and sharing your work later.

Class Properties

All blocks have the following properties. Some of them, such as CurrentPerson, are especially important and you'll find yourself using them often.

• BlockId - The Id of the current instance of the block.
• BlockValidationGroup - The unique validation group that the framework assigned to all the controls on the block.
• BreadCrumbs - The Breadcrumbs created by the page. A block can add additional breadcrumbs as described in the Breadcrumbs section.
• CurrentPageReference - URL for the page where the current block is located.
• CurrentPerson - The currently authenticated (logged in) person. If this is null, then the person viewing the block is not logged in yet.
• CurrentPersonAlias - The alias of the current person. In general you’ll want to use the PersonAlias when storing references to people. See the Using PersonAlias vs Person section below for additional details.
• CurrentPersonAliasId - The Id of the primary alias of the current person.
• CurrentPersonId - The Id of the current person.
• CurrentUser - The currently authenticated (logged in) user. This property has other properties such as: UserName and Person.
• RockPage - The page the block is currently on.
• RootPath - The fully qualified URL path to the root of the website running Rock.

Class Methods

The table below lists all the public methods available to use in your blocks. You can review them quickly since we'll cover some of the more important methods in the sections below.

• AddConfigurationUpdateTrigger( UpdatePanel upanel)
  Adds an update trigger to the given panel for when the block properties are updated.
• AddHistory(string key, string state, string title)
  Adds a history point to the ScriptManager.
• ContextEntity(string entityTypeName)
  Returns the ContextEntity of the entityType specified.
• ContextEntity()
  Return the ContextEntity for blocks that are designed to have at most one ContextEntity.
• GetAdministrateControls(bool canConfig, bool canEdit)
  Adds icons to the configuration area of a Block instance. Can be overridden to add additional icons.
• GetAttributeValue( string key )
  Gets the value of an attribute key.
• GetAttributeValues( string key )
  Gets the value of an attribute key - splitting that delimited value into a list of strings.
• GetBreadCrumbs( PageReference pageReference )
  Returns breadcrumbs specific to the block that should be added to navigation based on the current page reference. This function is called during the page's OnInit to load any initial breadcrumbs.
• GetUserPreference( string key ) (Obsolete; see Person Preferences)
  Returns the user preference value for the current user for a given key.
• GetUserPreferences( string keyPrefix ) (Obsolete; see Person Preferences)
  Gets the preferences for the current user where the key begins with the specified value.
• HideSecondaryBlocks( bool hidden )
  Sets the visibility of the secondary blocks on the page.
• IsUserAuthorized( string action )
  Evaluates if the CurrentPerson is authorized to perform the requested action.
• LinkedPageUrl( string attributeKey, Dictionary<string, string> queryParams )
  Builds and returns the URL for a linked page from a 'linked page attribute' and any necessary query parameters.
• LogException( Exception ex )
  Logs the given exception.
• NavigateToLinkedPage( string attributeKey, Dictionary<string, string> queryParams)
  Navigate/redirect to a linked page with the given parameters.
• NavigateToLinkedPage( string attributeKey, string itemKey, int itemKeyValue, string itemParentKey, int? itemParentValue )
  Navigate/redirect to a linked page with the given key, key-value and parent key, parent key-value. This is useful when navigating to a page that has a treeview that needs to expand the given parent item.
• NavigateToPage( Guid pageGuid, Dictionary<string, string> queryString )
  Navigate/redirect to the page specified by the provided Guid.
• NavigateToPage( Guid pageGuid, Guid pageRouteGuid, Dictionary<string, string> queryString )
  Navigate/redirect to the Page specified by the given page Guid using the PageRoute specified by the given page route Guid.
• NavigateToPage( PageReference pageReference )
  Navigate/redirect to the page.
• NavigateToParentPage( Dictionary<string, string> queryString )
  Navigates/redirects to the parent Page.
• PageParameter( PageReference pageReference, string name )
  Returns a specified page parameter from the specified PageReference. If a match is not found, an empty string is returned.
• PageParameter ( string name )
  Returns the specified page parameter value. The page's PageRoute is checked first and then query string values. If a match is not found an empty string is returned.
• PageParameters()
  Returns a Dictionary {String, Object} representing all of the page's page parameters.
• ResolveRockUrl( string url )
  Resolves a rock URL. Similar to the System.Web.UI.Control ResolveUrl method except that you can prefix a Url with '~~' to indicate a virtual path to Rock's current theme root folder.
• ResolveRockUrlIncludeRoot( string url )
  Resolves the rock URL and includes its web root.
• SaveAttributeValues()
  Saves the block attribute values.
• SetAttributeValue( string key, string value )
  Sets the value of a block attribute key in memory. Once values have been set, use the SaveAttributeValues() method to save all values to database.
• SetUserPreference( string key, string value ) (Obsolete; see Person Preferences)
  Sets a user preference for the current user with the specified key and value.
• SetValidationGroup( ControlCollection controls, string validationGroup )
  Sets the validation group for the given collection of controls.

QueryString

You're probably pretty comfortable with the QueryString, but we ask that you use the PageParameter( string ) method as a unified approach for fetching values from the QueryString, page route, etc. This method hides the complexity of having to find the value in any of those places.

if ( !Page.IsPostBack )
{
    string itemId = PageParameter( "CategoryId" );
    if ( !string.IsNullOrWhiteSpace( itemId ) )
    {
        ShowDetail( "CategoryId", int.Parse( itemId ) );
    }
    else
    {
        pnlDetails.Visible = false;
    }
}

Block Attributes

The Rock framework gives you an amazingly easy way to keep custom configuration settings for each Block. This feature lets you develop Blocks that are flexible, generic and configurable. We call these Block Attributes.

When a Block class is decorated with one or more Rock.Attribute field attributes, administrators can set values for each instance of the Block. (And thankfully Rock automatically builds the admin UI for setting the values.)

For example, let's say you were creating a block to cache some data and wanted to let the administrator decide how many minutes to keep it cached. Just add an IntegerField attribute above your block class declaration:

using Rock.Attribute;
[IntegerField( "Cache Duration", "Number of seconds to cache the content.", false, 0 )]
public partial class HtmlContent : RockBlock
{
    // ...

And in your code, use the GetAttributeValue( attributeName ) method to get the configured value.

int duration = Convert.ToInt32( GetAttributeValue( "CacheDuration") );

Notice how the key, CacheDuration, is simply the name specified in the attribution declaration with the spaces removed? This is a convention in Rock.

There are more than 30 different types of Block Attributes to get values such as booleans, campuses, dates, groups, memo and text fields – to name a few.

Accessing Preferences

Accessing preferences is handled by an instance of PersonPreferenceCollection. You don't need to create this yourself, it will be handled automatically by the RockBlock base class.

Person Preference Collection

Once you have your preference collection, all you need to do is call the methods below to access and update the values.

int pageSize;
// ...
var preferences = GetBlockPersonPreferences();
preferences.SetValue( "grid-page-size-preference", pageSize.ToString() );
preferences.Save();

// grid-page-size-preference will come from the block instance.
var preferences = GetBlockPersonPreferences();
string pageSize = preferences.GetValue( "grid-page-size-preference" );

// default-grid-page-size will come from the individual's global preferences.
var preferences = GetGlobalPersonPreferences();
string defaultPageSize = preferences.GetValue( "default-grid-page-size" );

int pageSize;
bool showDescription;
// ...
var preferences = GetBlockPersonPreferences();
preferences.SetValue( "grid-page-size-preference", pageSize.ToString() );
preferences.SetValue( "grid-show-description", showDescription.ToString() );
preferences.Save();

Preventing Validation

You can prevent a button, link, etc. from causing validation by setting the CausesValidation property to false:

<asp:LinkButton ID="btnCancel" runat="server" Text="Cancel"
   CssClass="btn btn-link" CausesValidation="false" OnClick="btnCancel_Click" />

You'll usually want to do this on cancel buttons, etc.

Custom Validation Group

If you need to add your own custom validators on controls, you should set the ValidationGroup property on the ValidationSummary control and then use that group name in controls on your block:

<asp:ValidationSummary ID="valSearchOrganization" runat="server" ValidationGroup="SearchOrg"
    HeaderText="Please Correct the Following" CssClass="alert alert-danger block-message error" />

<Rock:RockTextBox ID="tbSearchPostalCode" runat="server"
    Label="Zip/Postal Code" Required="true" 
    RequiredErrorMessage="Enter a zip or postal code to search"
    ValidationGroup="SearchOrg" />
    
<asp:RegularExpressionValidator ID="regSearchPostalCode" runat="server"
    ErrorMessage="Enter at least 4 characters" ControlToValidate="tbSearchPostalCode"
    ValidationGroup="SearchOrg" ValidationExpression="\w{4,12}" 
    CssClass="validation-error" Display="None" />
...
<div class="actions">
    <asp:LinkButton ID="lbSearch" runat="server" Text="Search" CssClass="btn btn-primary" OnClick="lbSearch_Click" ValidationGroup="SearchOrg" />
</div>

Service Layer

Nearly every entity in Rock has a corresponding <EntityName>Service class that handles loading (and storing) data from the database. When you use a service class, you'll need to give it a RockContext database context so it can communicate with the database.

The service classes will always have a Queryable() method for returning an IQueryable you can query using LINQ, but they will often have other methods for loading specific sets of data.

Examples

Let's use the PersonService class to illustrate a few ways you can get a person or a set of people.

// create a person service to perform different queries
var rockContext = new RockContext();
var personService = new PersonService( rockContext );

// a single person based on either their Id or Guid
var person = personService.Get( personId );
var person2 = personService.Get( personGuid );

// a collection of all people (including deceased)
var allPeople = personService.Queryable( includeDeceased: true );

// all males
var allMales = personService.Queryable().Where( p => p.Gender == Gender.Male )

// all people with the given email address
var matchingPeople = personService.GetByEmail( "ted.decker@rocksolidchurch.org" );

// all people with the matching partial phone number
var peopleWithPhone = personService.GetByPhonePartial( "1212" );

Certain service classes also return things other than collections of its corresponding entity. Some return a single entity, related entities, strings, or whatever is appropriate for that method. For example, the PersonService class has a method for getting a collection of families (Groups) for the given person. It also has methods for getting other things related to a person such as GroupMember, a GroupLocation, a PhoneNumber, etc.

// a collection of familes for the given "person" object
var familyGroups = personService.GetFamilies( person.Id );

// get the person's home phone number
var phone = personService.GetPhoneNumber( person, DefinedValueCache.Read( Rock.SystemGuid.DefinedValue.PERSON_PHONE_TYPE_HOME.AsGuid() ) );

Eager Loading Properties

You know how some entities have properties that are actually other entities? For example, a Group has a property called Members which is a collection of GroupMembers and a GroupMember has a Person property. If you know you're going to be querying and using those properties, you'll see significant performance improvements if you pass the property names to the Queryable() method.

Consider this example where the group members and member's names will be used to decide which groups you are fetching. Notice how the properties are passed as an include string by comma delimiting them if there are more than one. Also notice how you can refer to sub-properties via dot notation.

var rockContext = new RockContext();
var groupService = new GroupService( rockContext );

var query = groupService.Queryable( "Members,Members.Person" );

// only select groups whose members have someone with a nick-name 
// that starts with the given value.
if ( !string.IsNullOrWhiteSpace( nickName ) )
{
    query = query.Where( g => g.Members.Any( m => m.Person.NickName.StartsWith( nickName ) ) );
}

Read Only Queries

You should always add AsNoTracking()() on your queryable when you're not saving the collection back to the database. Doing so will significantly improve performance since it allows the Entity Framework to ignore certain bookkeeping activities. You'll need to include a using System.Data.Entity; to see this method.

var query = new PersonService( new RockContext() ).Queryable().AsNoTracking();
        

Just remember - you cannot do this if you are going to call SaveChanges() on the service.

ToList() Your DataSource

Make sure to call ToList() on your queryable collection if you're going to bind it to a DataGrid or use it as a DataSource somewhere.

var query = new PersonService( new RockContext() ).Queryable();

gPeople.DataSource = query.ToList();
gPeople.DataBind();

Caution When Saving Then Attempting to View Entity Properties

When you save a new entity using the service layer, be aware that Entity Framework will not automatically hydrate the related entity properties unless you use a new service (with a new RockContext) to re-fetch the item.

For example, a PrayerRequest has a relationship to a Category entity. Consider the case when we're setting a new prayer request's category by setting it's CategoryId property and then saving it:

var rockContext = new RockContext();
var prayerRequestService = new PrayerRequestService ( rockContext );
PrayerRequest prayerRequest = new PrayerRequest { 
    CategoryId = 9,
    // ...
};
prayerRequestService.Add( prayerRequest );
rockContext.SaveChanges();

You might wish that the prayer request's Category property would now reflect the correct category entity, however it does not. It is null. Even if you try to load it again using the same service after saving it, it will be null:

// Does not work
prayerRequest = prayerRequestService.Get( prayerRequest.Id ); // Warning!
var category = prayerRequest.Category; // THIS IS NULL

Instead, you need to fetch the item using a new service if you need the updated property as a fully hydrated entity:

// Will work
prayerRequest = new PrayerRequestService( new RockContext() ).Get( prayerRequest.Id ); // Good.
var category = prayerRequest.Category; // Now it's there.

Filter Options

If your grid potentially has too much data, you'll want to include a GridFilter control above your grid. Inside the GridFilter add any controls you'll use to collect filtering criteria from the user. Here is an example as seen in the PledgeList block which uses a PersonPicker to allow filtering by person, an account picker, and a date range picker.

<div class="grid grid-panel">
    <Rock:GridFilter ID="gfPledges" runat="server">
        <Rock:PersonPicker ID="ppFilterPerson" runat="server" Label="Filter by person" IncludeBusinesses="true"/>
        <Rock:AccountPicker ID="apFilterAccount" runat="server" Label="Filter by account" AllowMultiSelect="True"/>
        <Rock:DateRangePicker ID="drpDates" runat="server" Label="Date Range" />
    </Rock:GridFilter>
    <Rock:Grid ID="gPledges" runat="server" AutoGenerateColumns="False" AllowSorting="True" AllowPaging="True" OnRowSelected="gPledges_Edit">
        <Columns>
            ...
        </Columns>
    </Rock:Grid>
</div>

It will render a small Filter Options menu item in the top right corner above the grid.

Once expanded, it displays all the inner controls in the filter.

Of course, you still need to actually use the selected criteria to filter your data set – but don't worry it's pretty simple. Here's an example from the PledgeList block showing the user's criteria saved in a person preference and then used to filter the data in a BindGrid() method:

protected void gfPledges_ApplyFilterClick( object sender, EventArgs e )
{
    gfPledges.SetFilterPreference( "date-range", drpDates.DelimitedValues );
    gfPledges.SetFilterPreference( "person", ppFilterPerson.PersonId.ToString() );
    gfPledges.SetFilterPreference( "accounts", apFilterAccount.SelectedValues.ToList().AsDelimited(",") );
    BindGrid();
}
private void BindGrid()
{
    var pledgeService = new FinancialPledgeService( new RockContext() );
    var sortProperty = gPledges.SortProperty;
    var pledges = pledgeService.Queryable();
    int? personId = gfPledges.GetFilterPreference("person").AsIntegerOrNull();
    if ( personId.HasValue )
    {
        pledges = pledges.Where( p => p.PersonAlias.PersonId == personId );
    }
    var accountIds = gfPledges.GetFilterPreference( "accounts" ).Split( ',' ).AsIntegerList();
    if ( accountIds.Any() )
    {
        pledges = pledges.Where( p => p.AccountId.HasValue && accountIds.Contains( p.AccountId.Value ) );
    }
    // Date Range
    var drp = new DateRangePicker();
    drp.DelimitedValues = gfPledges.GetFilterPreference( "date-range" );
    var filterStartDate = drp.LowerValue ?? DateTime.MinValue;
    var filterEndDate = drp.UpperValue ?? DateTime.MaxValue;
    // exclude pledges that start after the filter's end date or end before the filter's start date
    pledges = pledges.Where( p => !( p.StartDate > filterEndDate ) && !( p.EndDate < filterStartDate ) );
    gPledges.DataSource = sortProperty != null ? pledges.Sort( sortProperty ).ToList() : pledges.OrderBy( p => p.AccountId ).ToList();
    gPledges.DataBind();
}

Override GetBreadCrumbs

Your GetBreadCrumbs() implementation will use the given page reference to get the id of the item in question, use that id to get that item's title, and then add a new BreadCrumb() onto a list of breadcrumbs that is returned to the caller.

You can see this happening in the ContentChannelItemView block:

public override List<breadcrumb> GetBreadCrumbs( PageReference pageReference )
{
    var breadCrumbs = new List<breadcrumb>();
    int? contentItemId = PageParameter( pageReference, "contentItemId" ).AsIntegerOrNull();
    if ( contentItemId != null )
    {
        ContentChannelItem contentItem = new ContentChannelItemService( new RockContext() ).Get( contentItemId.Value );
        if ( contentItem != null )
        {
            breadCrumbs.Add( new BreadCrumb( contentItem.Title, pageReference ) );
        }
        else
        {
            breadCrumbs.Add( new BreadCrumb( "New Content Item", pageReference ) );
        }
    }
    else
    {
        // don't show a breadcrumb if we don't have a pageparam to work with
    }
    return breadCrumbs;
}

Controlling Page Breadcrumbs Display Settings

Breadcrumbs can be disabled on a page and you can also control other aspects of the breadcrumbs under the Page Properties > Display Settings.

Your Own Edit Button

To use the edit button in the slide-out bar that opens when you click on the Block Configuration toolbar you can extend the RockBlockCustomSettings class instead of the usual RockBlock class. Once you do this, you only need to override and implement your own ShowSettings() method. That method will be called by Rock when a person with edit access clicks the edit button.

1 Slide-Out Bar

Shows a custom edit icon element added into the slide-out bar.

This example code from the DynamicReport block illustrates the concept. Here the block loads some data, binds some filters and then calls the Show() method of a model where all the custom stuff exists.

protected override void ShowSettings()
{
    pnlConfigure.Visible = true;
    LoadDropDowns();
    ddlReport.SetValue( this.GetAttributeValue( "Report" ).AsGuidOrNull() );
    txtResultsTitle.Text = this.GetAttributeValue( "ResultsTitle" );
    txtResultsIconCssClass.Text = this.GetAttributeValue( "ResultsIconCssClass" );
    txtFilterTitle.Text = this.GetAttributeValue( "FilterTitle" );
    txtFilterIconCssClass.Text = this.GetAttributeValue( "FilterIconCssClass" );
    BindDataFiltersGrid( false );
    ddlPersonIdField.SetValue( this.GetAttributeValue( "PersonIdField" ) );
    mdConfigure.Show();
}
                

Additionally, any block property you've given a category of CustomSetting will be hidden in the normal block settings. This is handy when you want to do something beyond the basics provided by the normal block settings area.

I Need More Control, Captain!

If you need more than a single edit pencil button, you can insert your own controls into the slide-out bar by overriding the GetAdministrateControls() method. This is exactly how the RockBlockCustomSettings class did it to get an edit button in the slide-out bar for you in the simple case.

This example code from a block illustrates the details:

public override List<control> GetAdministrateControls( bool canConfig, bool canEdit )
{
    List<control> configControls = new List<control>();
    // add edit icon to config controls if user has edit permission
    if ( canConfig || canEdit )
    {
        LinkButton lbEdit = new LinkButton();
        lbEdit.CssClass = "edit";
        lbEdit.ToolTip = "Edit HTML";
        lbEdit.Click += new EventHandler( lbEdit_Click );
        configControls.Add( lbEdit );
        HtmlGenericControl iEdit = new HtmlGenericControl( "i" );
        lbEdit.Controls.Add( iEdit );
        lbEdit.CausesValidation = false;
        iEdit.Attributes.Add("class", "fa fa-pencil-square-o");
        ScriptManager.GetCurrent( this.Page ).RegisterAsyncPostBackControl( lbEdit );
    }
    configControls.AddRange( base.GetAdministrateControls( canConfig, canEdit ) );
    return configControls;
}
                

In a nutshell, here's what's going on:

1. Create an empty list of controls.
2. Use the canConfig and canEdit boolean flags to decide if you want to add your items.
3. Create an appropriate control with an event handler.
4. Add it to the list of controls.
5. Register the control with the script manager.
6. IMPORTANT: add the standard set of controls by calling the base.GetAdministrateControls() method (unless you decide it's not appropriate for your block).
7. Return the list of controls.

That's all there is to it -- well, almost. You still have to write the code to actually do something when someone clicks the button you've added. In the example above, you would need to implement the lbEdit_Click() method.

RockDateTime vs DateTime

Because a Rock server is not always running or is not configured to be in the same time zone of the organization using Rock, you should always avoid creating new date/times or the current time (aka ".Now") using the standard system DateTime

Use the RockDateTime.Now or RockDateTime.Today static class methods when creating new date/times.

// Get the current date time
DateTime now = RockDateTime.Now;

// Get only the date component for today (wherever today is)
DateTime today = RockDateTime.Today;

If you're in need of checking the date/time of a file on the file-system, you should use the ConvertLocalDateTimeToRockDateTime( ... ) method to convert the time to a correctly adjusted time.

DateTime fileDateTime = File.GetCreationTime( file );
DateTime adjustedDateTime = RockDateTime.ConvertLocalDateTimeToRockDateTime( fileDateTime );

These methods always work because organizations set their particular time zone when they first install Rock. Behind the scenes, Rock stored a OrgTimeZone property into their web.config which is used by the Rock DateTime helper methods.

DateTime Formatting

For people, there is not one correct way to format dates and times. In some countries "MM/DD/YYYY" is the standard while in others it's "DD/MM/YYYY" or "YYYY-MM-DD" or one of hundreds of other styles. However, using the incorrect format isn't just a small issue, in some cases it will change the meaning of the date value to the viewer.

For the most part, the framework displays dates and times using the culture setting of the viewer's browser. However, to achieve this, when a date is stored in a string field (such as a string Attribute) you must set that string using the "Round-trip" (aka ISO 8601) format specifier "o" as shown here:

// set the value to the current time
thing.SetAttributeValue( attrKey, RockDateTime.Now.ToString( "o" ) );

Date, Time, DateTime Comparison

When writing LINQ (or SQL) queries where there is a Date, Time, Date/Time, or Numeric comparison involved, it's important to be consistent in how they are written. For example, if the user wants to filter the a list of records using a Date/Time range, do you use >= and < or > and <=?.

In general, we say let your start be "inclusive" and your end be "exclusive" as illustrated in each of the examples below.

DateTime range

var qry = new MyService().Queryable();

DateTime startDateTime = DateTime.Parse("11/1/2012 01:00 pm");
DateTime endDateTime = DateTime.Parse("11/2/2012 01:00 pm");

// Get the records equal to and greater than the StartDateTime, but just less than (but not equal)
// the EndDateTime.
qry = qry.Where( a => a.DateTime >= startDateTime && a.DateTime < endDateTime );

Date range

 var qry = new MyService().Queryable();

DateTime startDate = DateTime.Parse("11/1/2012");
DateTime endDate = DateTime.Parse("11/2/2012");

// For a little extra safety, since we are doing a Date comparison (not a DateTime comparison)
// get just the Date portion without the time (just in case).
startDate = startDate.Date;
endDate = endDate.Date;

// Get the records equal to and greater than the StartDate, but add a whole day to 
// the selected endDate since users will expect to see all the stuff that happened 
// on the endDate up until the very end of that day.

// calculate the query endDate before including it in the qry statement to avoid Linq error
endDate = endDate.AddDays(1); 

qry = qry.Where( a => a.DateTime >= startDate && a.DateTime < endDate );

Specific Date (of a DateTime column)

var qry = new MyService().Queryable();

DateTime startDate = DateTime.Parse("11/1/2012");

// For a little extra safety, since we are doing a Date comparison (not a DateTime comparison)
// get just the Date portion without the time.
// (just in case)
startDate = startDate.Date;

// When querying for stuff that occurred on a specific date, when the data is a DateTime,
// just add a day to the specific date to get records for the entire day.

// calculate the query endDate before including it in the qry statement to avoid Linq error
DateTime endDate = startDate.AddDays(1); 

qry = qry.Where( a => a.DateTime >= startDate && a.DateTime < endDate );

Specific Date (of a Date column)

var qry = new MyService().Queryable();

DateTime specificDate = DateTime.Parse("11/1/2012");

// Since we are doing a Date comparison (not a DateTime comparison) get just the Date
// portion without the time (just in case).
specificDate = specificDate.Date;

qry = qry.Where( a => a.LogDate == specificDate );

Time Range (when querying off of a Time column)

var qry = new MyService().Queryable();

TimeSpan startime = TimeSpan.Parse("01:00 pm");
TimeSpan endTime = TimeSpan.Parse("02:00 pm");

// Get the records equal to and greater than the startTime, but just less
// than (but not equal) the endTime.
qry = qry.Where( a => a.Time >= startTime && a.Time < endTime );

Time Range (when querying off of a DateTime column)

var qry = new MyService().Queryable();

TimeSpan startime = TimeSpan.Parse("01:00 pm");
TimeSpan endTime = TimeSpan.Parse("02:00 pm");

// We can't do DateTime.TimeOfDay in a queryable, so fetch it into a list first.
var list = qry.ToList();

// Get the records equal to and greater than the startTime, but just less than
// (but not equal) the endTime.
list = list.Where( a => a.DateTime.TimeOfDay >= startTime && a.DateTime.TimeOfDay < endTime)

Numeric range

var qry = new MyService().Queryable();

int startValue = int.Parse("100");
int endValue = int.Parse("150");

// Unless the UI has some text that explicitly states how the values are going to be
// compared, simply get the records equal to and greater than the startValue and
// less than or equal to the endValue. In other words, for integer comparison, do
// an "inclusive" compare

qry = qry.Where( a => a.Rating >= startValue && a.Rating <= endValue; )

QR Codes

There is also a GetQRCode.ashx handler to dynamically generate QR codes that can be embedded in web pages, printed on materials, etc. The QR codes are generated based on the text or URL you provide through the query string parameters.

To use this handler, you need to provide the data parameter in the query string, which will be encoded into the QR code.

The following parameters are supported by this handler:

• data - The text or URL to encode in the QR code. This is a required parameter.
• outputType - The image type to generate; either svg or png. (Default is png)
• pixelsPerModule - The pixel size each b/w module is drawn. (Default is 20)
• v17.0
  foreground - The color hex value to use for the foreground (b) color. Transparency is supported using RGBA values. (Default is #000000)
• v17.0
  background - The color hex value to use for the background (w) color. Transparency is supported using RGBA values. (Default is #FFFFFF)

/GetQRCode.ashx?data=ABC&background=%23FF5C0077

The example above generates a QR code that encodes the text ABC to output as a PNG with a semi-transparent orange background color.

Rock Internal

If a class, method, or property is decorated with the [RockInternal] attribute, then it should not be used.

Quick Reference

SQL: Custom Tables, Stored Procedures, User Functions

Custom tables should be prefixed with an underscore followed by your reversed, lowercase domain name, then your ProjectName -- replacing all dots with underscores.

Custom Namespaces, Classes, & Assemblies

Prefix your namespaces/classes & assemblies with your reversed, lowercase domain name, then your ProjectName.

namespace org.rocksolidchurch.MyProjectName
{
    public class Book
    {
        public int Id { get; set; }
        // ...

Private class properties should be prefixed with an underscore as illustrated here.

#region Fields

private int? _fooId;
private Note _note;

#endregion

Custom API

When developing custom API extensions, you must use a folder convention api/<com.domain>/ (such as api/org.rocksolidchurch/) to avoid collisions with other custom developer APIs.

Standard Control Variable Naming

If you really want to make the core team happy, you can follow these naming conventions on your entity property/fields:

Standard Field/Property Naming

We'd also recommend these naming conventions on your entity property/fields:

Utility Class Naming Conventions

Lastly, here are a few conventions for any UI controls you might create: