ACF how to write

This material is work-in-progress ... Do not follow instructions here until this notice is removed. (Last edited by Ncopa on 12 Mar 2012.)

How to Write an ACF Under Construction

For some examples please see git

http://git.alpinelinux.org/cgit/

• acf-shorewall
• acf-dhcp
• ...

From <nil> to a running ACF example application

Step 1 - The Programming Language

• ACF uses lua as its programming language. Have a look at lua.org before starting.

Step 2 - The Development Environment

• Setup an ACF Development Environment: Getting_started_with_ACF_development

Step 3 - Create A Development Directory

Once you entered the ACF Development Environment as described in step 2:

• in your user home create a directory for your application (e.g. mkdir ~/myapp)
• and cd into it (e.g. cd ~/myapp)

Step 4 - MVC, How Does It Affect My Coding?

ACF is an MVC based framework. What does this mean to you? Your application is separated into three layers: Model, View, Controller - each of which has one or more files.

• Model: The 'real work' is done in the Model (e.g. modifying config files, starting/stopping services etc.)
• View: This is where you define what your application will look like. You can have one or more View files, each presenting a dynamic HTML page with only as much code as necessary to format the data you receive from the Controller.
• Controller: The event dispatcher. In the Controller, you create one function per action. If the user loads the respective 'event page' (web), ACF will fire an action - the same-named function in controller will be called. This function then retrieves necessary data from the Model and passes it to the View to be displayed to the user.

Step 5 - The Example Files To Start With

Now let us have a look at the files we need to place into our application directory:

• Makefile
• config.mk
• myapp-model.lua
• myapp-myview-html.lsp
• myapp-controller.lua
• myapp.roles
• myapp.menu

Makefile:

The Makefile is called to install our ACF application so that we can see it working.

APP_NAME=myapp
PACKAGE=acf-$(APP_NAME)
VERSION=1.0_alpha1

APP_DIST=myapp-model.lua        \
         myapp-myview-html.lsp  \
         myapp-controller.lua   \
         myapp.roles            \
         myapp.menu

EXTRA_DIST=README Makefile config.mk

DISTFILES=$(APP_DIST) $(EXTRA_DIST)

TAR=tar

P=$(PACKAGE)-$(VERSION)
tarball=$(P).tar.bz2
install_dir=$(DESTDIR)/$(appdir)/$(APP_NAME)

all:
clean:
        rm -rf $(tarball) $(P)

dist: $(tarball)

install:
        mkdir -p "$(install_dir)"
        cp -a $(APP_DIST) "$(install_dir)"

$(tarball):     $(DISTFILES)
        rm -rf $(P)
        mkdir -p $(P)
        cp $(DISTFILES) $(P)
        $(TAR) -jcf $@ $(P)
        rm -rf $(P)

# target that creates a tar package, unpacks is and install from package
dist-install: $(tarball)
        $(TAR) -jxf $(tarball)
        $(MAKE) -C $(P) install DESTDIR=$(DESTDIR)
        rm -rf $(P)

include config.mk

.PHONY: all clean dist install dist-install

Remark: Should you create additional application files (view files for example), don't forget to place their names in Makefile under APP_DIST otherwise they will not be installed later on and your application will fail with an error message.

config.mk: For use with the Makefile. Just copy/paste it. We will look at it later.

prefix=/usr
datadir=${prefix}/share
sysconfdir=${prefix}/etc
localstatedir=${prefix}/var
acfdir=${datadir}/acf
wwwdir=${acfdir}/www
cgibindir=${acfdir}/cgi-bin
appdir=${acfdir}/app
acflibdir=${acfdir}/lib
sessionsdir=${localstatedir}/lib/acf/sessions

myapp-model.lua:

-- acf model for myapp
-- Copyright(c) 2010 <Your name here> - Licensed under terms of GPL2
module (..., package.seeall)

cfgfile = "/tmp/myfile"

-- This function returns a cfe (table of values) containing the file's
-- value as a string. If the file does not exist, we'll
-- simply return "" (an empty string, but NOT nil)
readfile = function()
   retval = ""
   fileptr = io.open( cfgfile, "r" )
   if fileptr ~= nil then
      retval = fileptr:read( "*a" )
      if retval == nil then
         retval = ""
      end
      fileptr:close()
   end
   return cfe({ value = retval, label="File data" })
end

-- This function will write new contents into our file
writefile = function( newcontents )
   fileptr = io.open( cfgfile, "w+" )
   if fileptr ~= nil then
      fileptr:write( newcontents )
      fileptr:close()
   end
   return
end

myapp-myview-html.lsp:

<% form, viewlibrary, pageinfo, session = ... %>
<h1>MyApp - MyView</h1>
<form action="" method="POST">
  <textarea name="textdata"><% io.write( form.value.file.value ) %></textarea>
  <input type="submit" name="cmd" value="update">
</form>

myapp-controller.lua:

-- the myapp  controller
module (..., package.seeall) 

myview = function( self )
   -- self.clientdata contains the data from the HTML form
   -- in your myapp-myview-html.lsp
   local clidat = self.clientdata  

   -- user did submit the form (not just call the page)
   if clidat.cmd then
      if clidat.cmd == "update" then -- user pressed update button
         self.model.writefile( clidat.textdata )
      end
   end
   value = self.model.readfile()
   return cfe({ type="form", value={file=value} })
end

myapp.roles:

GUEST=myapp:myview

myapp.menu:

# Cat   Group   Tab     Action
Test    MyApp   MyView  myview

Step 6 - What Does It Do?

This program just displays a <textarea> box and a submit "update" button. The user can enter text that is saved into a file once he presses "update".

In Depth

Now let us have a closer look at the different files' contents:

myapp-model.lua

The functions defined in here can be accessed by the controller to update/set/retrieve data, start/stop services, basically do any 'real work'.

myapp-myview-html.lsp

This is our view. It receives the data to be displayed from the controller. The view has access to the table returned by the controller action along with a helper library, a table of page information, and the session data (see the first line .. <% .. %>). The view can also load other libraries, but it should not directly access the controller, model, or any global variables.

myapp-controller.lua

The controller is an event dispatcher. So, in here you define all the actions that the user can call or that are defined in the menu. Each action is a separate function that will receive self as the only parameter.

In our case the action is myview.

For every action you define here, you can define a separate view file using the nameage: myapp-action-html.lsp

If there is no view file for a specific action, the application will look for a generic view file using the nameage: myapp-html.lsp

This function can call the model's functions to update and/or retrieve data (e.g. self.model.readfile()).

Anything that this function returns will be passed on to the view

myapp.roles

This file determines which users have access to which controllers and views. A separate roles file is generally defined for each ACF. The format of the files is as follows:

group=controller:action[,controller:action]

Each line defines controller:action combinations that are permitted for a particular group. GUEST is a special group to which all users, including anonymous users, are members.

myapp.menu

In this file you define:

• The Category in which a menu entry for your program will appear
• The Group menu name under Category for this controller
• The Tab name on the controller page
• The Action with-in your controller that will be called once the user clicks on the menu entry or tab defined by Category, Group, and Tab.

How to exchange data between model-view-controller?

To exchange data between model, view and controller ACF uses Configuration Framework Entities (CFE).

Please see ACF_core_principles for further details on CFEs.

Step 7 - How To Get It Going?

Once you have completed all the above mentioned steps, go on with:

• sudo make install (this will install your app with the http server)
• point your browser to http://ip-of-your-dev-host/