Website Templates and Custom Renderers
There are basically two ways to customize web sites generated by CodeFluent Entities:
1) edit the generated files in place. The generated code is very readable, and by design easy to customize.
2) modify how the out-of-the-box site is generated. Please note these auto-generated sites are very well suited for back-end/back-office/administration/testing/sample purpose. However, they are generated using site templates, and these templates can be customized. We will try to explain how.
Site templates are located in \Program Files (x86)\SoftFluent\CodeFluent\Modeler\Templates\UI. Here you will find the various templates for ASP.NET, MVC, Ajax, etc…
These templates are a good start to build your own. Each template is composed of two directories:
- A directory that contains a cf_template.xml which is the template manifest, used by tools such as Visual Studio. Let’s say it’s named ‘MyAspNet’ for our example.
- Another directory named [directoryName]_Renderers. So it should be named MyAspNet_Renderers for our example.
Both directories can contain template files (text files with the .tpl extension) or any other files. Template files are files that are executable files and can run in the context of the model being produced (more here:http://www.softfluent.co…_TheTemplateEngine.html and here: http://www.softfluent.co…s_TemplateProducer.html).
The first directory will define the target site files. The renderers directory will contains the renderers implementation. Now the question: what is a renderer?
A renderer in a CodeFluent Entities model is an abstract platform-independent item which basically has two important properties: a name, and a type (unspecified, read, write, create, column, parameter), and will be used to define how a concept will be rendered ultimately on a specific platform (whatever that platform will be: web, winforms, WPF, etc.).
Renderers can be associated with properties, view properties, entities or method parameters. Renderers can be shared.
For example, let’s suppose you handle a lot of IP Address in your application. There’s nothing built-in in the product but many entities have properties that are of the IP Address type. Then, you would declare a renderer named ‘IPAddress’ (for example) and associate this renderer to all the properties of that type.
At production time, a producer such as the ASP.NET producer will relate the renderer definition to a concrete UI artifact using it’s name and type. In the case of the ASP.NET producer, a renderer will be simply represented by a file, containing some HTML (or ASP.NET) fragment. You can see what the out-of-the-box renderers look like if you open the files in the [directory]_Renderers directory of the out-of-the-box templates. A renderer file name starts with “Renderer.”.
Let’s go to CodeFluent Entities installation directory, and navigate through the Templates\UI directory. Here you can see a set of folders containing the templates and renderer.
We’re going to create a new template from an existing one and also add a renderer. To do so copy the following folders to a folder called “UI” in the location of your choice (Note the folder root must contain ‘UI’):
Rename the last two copied folders like this:
- You should have something like this:
We We copied two website templates because the AspNetWebForms template inherits the AspNet template.
You can already customize your website here. For instance edit CustomWebsite\Default.aspx.tpl, and modify the page title by modifying the
<%@ Page %> tag with something like this:
<%@ Page Title=”This is my Custom Website Home Page” …
Now add a new file called Renderer.MyContactSource.tpl in the CustomWebsite_Renderers folder. Open this file in a text editor such as NotePad and type the following text: “this is my custom Contact Source”. It is an unspecified renderer because the file name does not end with Write, or Column for example.
Now start Visual Studio, and create a CodeFluent Entities project (Demo.ContactManager, C#, SQL Server, ASP.NET WebForms). Go in the Contact Entity, select the ContactSource property and add a ‘MyContactSource’ renderer of unspecified type:
Now, double-click on the ASP.NET Webforms producer, and configure it to point to your custom site template:
Build the project, and execute the generated web site. You should now see this when you try to Add or Edit a new Contact:
what happened is, at generation time, every time a property is associated with the MyContactSource renderer, it will be rendered using the content of the Renderer.MyContactSource.tpl file. This file just contain a pure (HTML) text, but it could contain anything you would like, including server-side ASP.NET controls. This file can also contain template code so you can indeed have it vary using the model and the source object it was instantiated from at generation time.
For example, if you don’t like the drop down list that’s used to represent relations by default, you can just modify the Renderer.Relation.Write.tpl content and this will change how relations are rendered (in write mode) in every screen of the application, because Relation is the name of the default renderer associated with M:0/1 or 0/1:M relations. Association is the name of the default renderer associated with M:N relations.
Besides, navigate back to the homepage and note that Tab’s title reflects our change made in the Default.aspx file.
Therefore, thanks to Renderers and custom templates you can generate full customized websites.