Creating a component from scratch

Let's create some components from scratch. We start with a 'Page' component, and later on we will make some re-usable components like inputfields, checkboxes etc.

A few notes:

• For the examples in this wiki i'm using the HTML/CSS layout that comes with handleview, since this wiki is not about creating a website from scratch.
• I tend to organize my html component templates in a slightly different way than Alain does, and these examples will use my structure.
• Everything is case-sensitive, so if you are typing things over from these tutorials make sure you pay attention to uppercase and lowercase
• I like to use 'camelCase' syntax, and i'm not about to start any arguments about that.
• In VBA i follow Alain's naming conventions ( prefixing Models wit 'm_', Classes with 'c_' etc)
• I assume you have at least some experience with VBA and understand the difference between classes and modules.

And a few experiences

• In your HTML editor make sure that tabs are inserted as spaces. Vba does not like tabs!
• Use some pen and paper to write down the different name variations you'll be using, because in VBA you'll be jumping between a few files where you'll need them.
• Make a pure HTML version of your website...The WebbrowserControl does not have developer tools, so debugging the html/javascript inside MS Access is a real pain.
• Have an 'open mind' , always remember that you are building an MS Access application, not a website. Some methods to get stuff working may seem a little verbose.

The HTML template;

Each component must have a HTML template, so let's start with that.

• Create the file "/components/Pages/page.myfirstpage.html"
• paste this html in it;

    <component class="flex-grow-1">
      <div class=" p-5">
        <div class="xhv-title">This is my first page./div>
      </div>
    </component>

A few things to notice here:

• A template starts with <component> and MUST be on line 1 of the file
• The component tag will be part of your final html. So if you need to style it...do it!

Note: the tag can be named anything you want as long as you don't use official HTML tagnames, so <pagecomponent> is also valid )

That's it for the html part...let's go to MS Access

The VBA Component

• Open the database "HandleView.DevPreview.0.0.1.accdb" and then go to the editor
• import the class file "c_ComponentTemplate.cls" from the vba folder.
• rename it to "c_Page_MyFirstPage"
• Open the file and make the following changes (it's at the top of the class);

   Const COMPONENT_NAME_TYPE As String = "pageMyFirstPage"
   Const TEMPLATE_URL As String = "components\Pages\page.myfirstpage.html"

Make sure the path points to the html template we just created

• Open the class "xhvComponentFactory"
• In here you'll find a 'Select Case' statement, add the following lines to it

      Select Case UCase(componentName)
        'add line here
       Case "PAGEMYFIRSTPAGE" 
        Set createComponent = New c_Page_MyFirstPage

Note: the name you use at Case is the name you put in your component at Const COMPONENT_NAME_TYPE As String in Uppercase.
The name you use at Set createComponent is the name of the class file

• Open the module mod_xhvConfigRouter
• add the following on the position that says "add these lines here"

Public Sub configureRoutes()

    Dim oRoutes As Collection
    Dim oRoute As xhvRoute
    Set oRoutes = New Collection

   'add these lines here

    Set oRoute = New xhvRoute
    oRoute.path = "myFirstPage"
    oRoute.routerPortName = "content"
    oRoute.componentName = "pageMyFirstPage"
    oRoute.exitGate = ""
    oRoute.securityGate = ""
    oRoutes.Add oRoute

Okay, let's recap; We should now have;

• a class named "c_Page_MyFirstPage"
  • with component name "pageMyFirstPage"
  • that points to our html template at "\components\Pages\page.myfirstpage.html"
• we configured a route named "myFirstPage"
  • that will render component "pageMyFirstPage" inside a routerport named "content"

  Note: that xhv-routerport is already placed in "components\appComponent\app.component.html" , our main component

• we registered our component in `xhvComponentFactory"

That's it... our component is ready !
The only thing left to do is actually use it...

We need to create a menu link to open the page.

• Open the file (HTML) "\components\topBarComponent\topBar.component.html"
• add a link just below the "Home" link

 <ul class="navbar-nav mr-auto">
      <li class="nav-item active">
        <a class="nav-link" href="#" xhv-eventlistener xhv-event="click" xhv-eventhandler="navigateHome" xhv-params="">Home<span class="sr-only"(current)</span></a>
      </li>
   <!-- add our link here -->
     <li class="nav-item active">
      <a class="nav-link" href="#" xhv-eventlistener xhv-event="click" xhv-eventhandler="navigateFirstPage" xhv-params="">My first page</a>
     </li>

Let's run this through;

• "xhv-eventlistener" tells HandleView it needs to treat this as an interactive element.
• "xhv-event='click'" tells HandleView what kind of interaction it is going to be
• "xhv-eventhandler='navigateFirstPage'" is the function we are going to call in our VBA component
• "xhv-params=''" We are going to have a lot of fun with this one...in later episodes. For now, leave it the way it is.

Note: although the attribute `xhv-params' is an empty string, it MUST be placed. ATM Handleview always expect this attribute.

Wait! A function called 'navigateFirstPage' ?? Where can i find that function ?
Well... we'll have to create it...
The place where we call this function - in this case the template for component 'topBarComponent' - determines where this function should be. In this case it is expected to be in the component 'topBarComponent'. So let's do that.

In MS Access open the class 'c_TopBar_Component' and scroll all the way down until you find

Public Function navigateHome(ParamArray args() As Variant) As Boolean
    xhvRouter.navigate "home/{'id':1}"
End Function

Copy this function , paste it underneath and make the following changes

Public Function navigateFirstPage(ParamArray args() As Variant) As Boolean
    xhvRouter.navigate "myFirstPage"
End Function

• The function name is the same name we used in the link as xhv-eventhandler
• The name after xhvRouter.navigate is the same name we used in our router configuration as oRoute.path = "myFirstPage"

Cool! Save everything and start your App.

But why all this trouble to show a page?

You are right...there is absolutely no reason why we should do this just to show a simple page.

You should only create a component if it needs to interact with data from MS Access
But remember...this was just your first step in the HandleView world... Next time we are going to do something useful with our 'first page'