Developer 101 - Lab: Create an Image Link Module

In this lab, we will create a module that displays an image wrapped in an anchor. Again, you will need to have the Agility Content Manager open in a web browser and our Sample Site open in Visual Studio. At the end of the lab, you will have created a module definition and added an instance of it to a page.

1. First, we need to define our module definition. Navigate to the Settings page in Agility, and select Module Definitions.

2. Click on New Module Definition. Give the new module a Name of “Image Link” - the Reference Name will be auto-populated. It is important to add a meaningful description here so that content editors know what to expect, so set the value to something like “Renders a clickable image.”

   
   

3. Now click on the Form Builder tab, so that we can start adding the fields/properties of the module.

4. Click Add Field and the Field Properties dialog will appear. Give the first property a label of “Title”, the Name field will auto-populate. Leave the property type drop-down as “Text” and leave the default value empty. Make sure the “Required” checkbox is checked, so that this property cannot by left blank by content editors.
   
   

5. Click on Save & New to apply this property and create another. Give the second property a label of “Image”, and set the property type to “Image”. You’ll notice that the Image type enables some additional fields – File Size, Width, Height and Valid File Types. If your website design dictates that only a certain size of file will fit, you should populate these fields. For this example, we’ll leave them as the defaults. You will also notice a tab called “Thumbnails” – this allows you to specify Thumbnail references so that you can automatically generate different sized images based on the Image being uploaded. This is less important than it used to be since the Agility Media & Documents now supports Ad-hoc thumbnailing - so thumbnails no longer need to be defined before-hand.
   
   

6. Click on Save & New again to store this property and create another new one. Give the third property and Label of “Link URL”, and set the property type to “URL”. Make sure the “Required” checkbox is checked, and click on Save & Close.

7. Now that we have our field properties, the last step is to set our Output Template. Navigate to the Output Template tab and select Partial View on Website. Set the Partial View Path to “~/Views/Modules/ImageLink.cshtml”. Click on Save & Close to finish creating the module definition. 

8. Still in Agility, navigate to Pages and select a page. In a Module Zone, click on +Add and locate the newly-created “Image Link” module. This will open the module’s input form.

9. Usually, you would take this opportunity to view the Module’s input form from a content editor’s perspective and fill in the form. Do the fields make sense? Is there enough instruction for the content editor to be able to fill out the form in confidence? If not, go back to the drawing board and re-adjust your module properties. If you are satisfied continue filling in the form.

10. We need to populate the Title, Image and Link URL fields. For the image, click on Browse, and then Upload File in the documents dialog that appears. Locate the file that you want to upload. Click on Open and the file will be uploaded - click on OK to attach the image to the module. The file is now selected, and you can add a meaningful value to the Alt Text field for display on the website. Note that the Alt Text field is not mandatory, but it is good practice to have one for SEO and Accessibility.

11. Next populate the Link URL by entering a URL of your choice. Note that you can also utilise the URL field by selecting a document from the Media & Documents list or a page from your sitemap by clicking the Choose File or Choose Page Enter the title of the link as appropriate, and change the target drop-down to “New Window”.

12. Click Save & Close to finish editing this instance of the module.

13. We can now create the partial view that will display the module in the website code. Switch to Visual Studio and a new partial view in the ~/Views/Modules directory called “ImageLink.cshtml”.
    
    

14. Next, switch back to Agility and navigate to Settings > Developer Downloads. Click on the link Content Definition API, to download the latest Model objects for your project file. You can also download this file from within Settings > Module Definitions and Settings > Content Definitions. Locate the existing file in your solution - usually located in the Models You can then copy the objects from the new file into the existing one. Be careful with this, as the C# Namespace generated in downloaded API may not be the same as what you have defined in your website code. In this particular case, the downloaded API has the namespace of “SampleMVC” and your project’s Models has a namespace of “MVC4SampleSite.Models”. To get around this, simply copy all the classes without the Namespace and replace the existing classes. Build your project to ensure there aren’t any typos or missing braces.
    
    Pro Tip: Update your strongly-typed API from within Visual Studio - Download the Agility CMS Model Updated Visual Studio Extension

15. We now need to tell the new View what type of data to expect. Assuming the namespace of your class is "MVC4SampleSite.Models" (check the top of your API file), add the following line to the top of your new partial view:

    @model MVC4SampleSite.Models.Module_ImageLink

16. We can now reference the Model's properties to build some markup for the view – taking full advantage of Visual Studio’s intellisense. At this point you can create the markup however you wish, but use the example below to illustrate how to reference the Model's properties with Razor syntax:
    
    

    @model MVC4SampleSite.Models.Module_ImageLink
    
    
    <h1>@Model.Title</h1>
    <a href="@Data.UrlEval(Model.LinkURL, "url")" target="@Data.UrlEval(Model.LinkURL, "target")">
        <img src="@Model.Image.URL" alt="@Model.Image.Label" />
    </a>
    

17. Save the file and build your solution. In your browser, navigate to http://localhost:{port-number}/{your-page}. You will now be able to see your Image Link module displayed on the page.