Thursday 4th December, 2014

Editor 1.4 beta - .NET

When Editor was originally developed, it was clear that a suite of libraries should be available for the server-side that compliment the client-side Javascript library and make installation of the software as simple as possible. At the time it was decided that PHP libraries would be the initial focus (after all, PHP does enjoy a majority market-share). However, the intention has always been to develop libraries for other server-side environments.

I'm delighted to announce today the realisation of that dream with the release of Editor 1.4 beta which adds .NET libraries to the Editor suite of tools. There are also a number of changes in the PHP libraries to increase flexibility and in the Javascript component as detailed below, but the primary focus for this release is the new .NET libraries.

.NET

The .NET framework is immensely powerful and drives a huge number of the business sites around the world. With the recent announcement from Microsoft that .NET core has been open sourced and will run on Mac and Linux computers in the future, it is an exciting time to be joining the .NET ecosystem.

The libraries included in the Editor package for .NET enjoy feature parity with the Editor PHP libraries and the two will be developed in tandem in future. There are of course a few .NET specific features, such as the ability to work with models in a seamless fashion (as you might expect in an MVC application) and small API changes to match .NET development conventions, but in future, if a feature is added to one of the libraries, expect it to also be present in the other!

New documentation has been published on the Editor site that details how to:

Install and run the standard Editor examples (a Visual Studio project is available for download on the download page)
The basic concepts of the Editor libraries
Use with Web API and ASP.NET MVC
And more
A detailed API reference is also available

Client-side

It is worth noting that the Javascript examples and documentation presented on this site are fully compatible with the .NET framework. No changes are required to have Editor interact with the new .NET libraries for Editor. The Editor libraries have been designed with that specifically in mind to ensure that the Javascript programming environment is common to both the supported PHP and .NET libraries.

Web API

As an example showing how easy it is to use Editor in .NET, this code snippet shows how the libraries can be used with Web API (more details):

public class StaffController : ApiController
{
    [Route("api/staff")]
    [HttpGet]
    [HttpPost]
    public IHttpActionResult Staff([FromBody] FormDataCollection formData)
    {
        DtResponse response = new Editor(Db, "staff")
            .Model<StaffModel>()
            .Process(formData)
            .Data();
 
        return Json(response);
    }
}

You'll be able to note that on line 9 the StaffModel is used to describe the data that should be read from the database, shown in the table and made editable. The Field() method can also be used to describe fields and add fine grain control over them.

MVC

The same Web API example shown above, but for ASP.NET MVC is very similar (in this case standard routing is used rather than attribute routing, which could also be used if required):

public class StaffController : Controller
{
    public ActionResult Table()
    {
        DtResponse response = new Editor(Db, "staff")
            .Model<Models.StaffModel>()
            .Process(Request.Form)
            .Data();
 
        return Json(response, JsonRequestBehavior.AllowGet);
    }
}

Missing from the beta

The .NET Editor libraries are beta software and it would be much appreciated if you could report any issues that you run into.

Additionally there are a couple of areas which are not included in the pre-release software, but will be added before 1.4.0 final is released:

1-to-many join support. The PHP libraries provide a join() method to give this ability, which will be added during the beta.
Generator support. Generator will create all of the code needed for simply projects to give you a quick kick start. This will also be added during the beta.

PHP

While much of the development focus has been on the new .NET libraries, the PHP component of Editor has also seen a number of improvements:

Fine grain get and set control
Multiple validators
Automatic options

Fine grain get and set control

Previously it was possible to control whether a field was read / write, read-only or write-only. This is still possible, but using the set() method it is now also possible to control if the field is set on create or edit actions. This gives the ability to use fields which are set only at row creation or update time, such as timestamp fields showing when the row was created or last edited.

In addition to this, the new setValue() and getValue() methods also provide the ability to give a value that will be used regardless of any value read from the database (in the case of get) or from the client-side Editor (in the case of set).

Consider for example a created field which should have a timestamp set when created (not sent from the client-side) and also have the value read when DataTables requests the data for the table:

new Field( 'created' )
    ->set( FIELD::SET_CREATE )
    ->setValue( time() );

Multiple validators

It is now possible to provide multiple validators for a single field. The field must pass all validators in order to be considered valid. For example, consider an e-mail address input field that must be unique. The email and unique validators can be used in tandem:

new Field( 'email' )
    ->validator( 'Validate::email' )
    ->validator( 'Validate::unqiue' );

Automatic options

When working with joins it is quite common to want to get a list of options from the joined table to allow the end user to select a value from a limited set. Previously with the Editor libraries this required a custom SQL call to the database and custom code in initComplete on the client-side, but now a new Field options() method is available which will do this for you, selecting the data, sending it back to the client-side, where the data will automatically be populated in the field.

Consider for example a select field which should have its list of options populated from a joined table. A single call to options() is all that is now required now:

new Field( 'users.site' )
    ->options( 'sites', 'id', 'name' );

The join examples on the Editor site now all make use of this method to populate joined fields.

Javascript

In the Editor Javascript library the most significant change is support for the new editField option in the DataTables initialisation. This is designed to make using inline and bubble editing with joined data much easier.

When using inline() and bubble(), Editor will automatically attempt to determine which data point should be edited based on the information available to it and DataTables - matching on the column and field names.

However, when using a join table it is not uncommon to use one data point in the table for display and another as the value to be edited. This would result in an error from Editor, and require the field name to be specified in the API call.

The editField option adds an option to the DataTables columns options that will inform Editor which field to edit. Consider for example the following columns definition:

columns: [
    { data: "users.first_name" },
    { data: "users.last_name" },
    { data: "sites.name", editField: "users.site" }
]

In this case while the DataTable will display the sites.name value, Editor will edit the users.site field! This use case can be seen live in the Editor examples.

Beta feedback

This release of Editor is very exciting, but it is beta software. I would very much encourage you to download the beta (be it .NET or PHP that you are interested in!) and let me know how you get on. If you do report a bug, please ensure that you provide a full description of the issue, and ideally a link to the page you are working on.

I hope you enjoy using Editor!