ajaxed v2.1 API Documentation


Introduction: How to read the ajaxed API Docs
(Recommended read if you are using ajaxed for the first time)

Previous API docs: v2.0.1   v2.0  

Class AjaxedPage ^

buffering, callbackFlagName, callbackType, contentType, DBConnection, debug, defaultStructure, headerFooter, loadPrototypeJS, onlyDev, plain, title

ajaxedHeader, draw, error, execJS, getLocation, iif, isCallback, isPostback, loadCSSFile, loadJSFile, QS, QSHas, QSP, QST, return, returnValue, RF, RFA, RFE, RFHas, RFP, RFT, throwError, write, writeln
Represents a page which is located in a physical file (e.g. index.asp). In 95% of cases each of your pages will hold one instance of this class which defines the page. For more details check the /ajaxed/demo/ for a sample usage.

Example of a simple page (e.g. default.asp):

<!--#include virtual="/ajaxed/ajaxed.asp"-->
<%
set page = new AjaxedPage
page.title = "my first ajaxed page"
page.draw()
sub main()
    'the execution starts here
end sub
%>
Furthermore each page provides the functionality to call server side ASP procedures directly from client-side (using the javascript function ajaxed.callback()). A server side procedure can either return value(s) (all kind of datatypes e.g. bool, recordset, string, etc.) or act as a page part which sends back whole HTML fragments. In order to return values check return() and returnValue() for further details. Page parts can be used to update an existing page with some HTML without using a conventional postback. Simply prefix a server side sub with pagePart_ and call it with ajaxed.callback(pagePartname, targetContainerID):

<% sub pagePart_one() %>
    <strong>some bold text</strong>
<% end sub
sub main() %>
    <div id="container"></div>
    <button onclick="ajaxed.callback('one', 'container')">load page part one</button>
<% end sub %>
  • Refer to the draw() method for more details about the ajaxed.callback() javascript function.
  • Whenever using the class be sure the draw() method is the first call before any other response is done.
  • The main() sub must be implemented within each page. You have to implement callback(action) sub if callbacks are used.
  • init() is always called first (before main() and callback()) and allows preperations to be done before any content is written to the response e.g. security checks and stuff which is necessary before main() and callback().
  • After the init() always either main() or callback() is called. They are never called both within one page execution (request).
  • main() represents the common state of the page which normally includes the page presentation (e.g. html elements)
  • callback() handles all client requests done with ajaxed.callback(). It needs to be defined with one parameter which holds the actual action to perform. As a result the signature should be callback(action). Example of a valid callback sub
  • 
    <%
    sub callback(action)
        if action = "add" then page.return(2 + 3)
    end sub
    %>
    
  • Requires Prototype JavaScript library (available at prototypejs.org) but can be loaded automatically by ajaxed (turn on in the config)
  • access querystring and form fields using page methods:
  • 
    <%
    sub main()
        id = page.QS("id") ' = request.queryString("id")
        name = page.RF("name") ' = request.form("name")
        save = page.RFHas("save") 'checks if "save" is not empty
        'automatically try to parse a querystring value into an integer.
        id = str.parse(page.QS("id"), 0)
    end sub
    %>
    
  • The page also supports a mechanism called "page parts".
  • use plain property if your page is being used with in an XHR (there you dont need the whole basic structure)
  • Meta

    Properties

    Methods

    Initializations


    Class Cache ^

    interval, intervalValue, maxItemSize, maxSlots, name

    clear, getItem, store
    Lets you cache values, objects, etc. It uses the application-variables and therefore the cache will be shared with all other users. it can cash items which are identified by an Identifier. The cache will be identified by its name The cache is protected against memory problems. e.g. huge contents wont be cached, cache has a limited size. so that the server is not to busy you can define how the caching works for a specific thing. e.g. you want to cache RSS Feeds then you can setup that the cache for RSS will hold a maximum of 10 RSS feeds shared. The organisation of the cache is done automatically if the maximum amount of items is reached

    Meta

    Properties

    Methods


    Class Database ^

    clientCursor, connection, dbType, defaultConnectionString, numberOfDBAccess, stringFieldTypes

    close, count, delete, getRecordset, getRS, getScalar, getUnlockedRecordset, getUnlockedRS, insert, insertOrUpdate, open, openDefault, SQLSafe, toggle, update
    This class offers methods for database access. All of them are accessible directly through db without creating an own instance. The AjaxedPage offers a property DBConnection which automatically opens and closes the default connection within a page.
  • the database type is automatically detected but it can also be set manually in the config (AJAXED_DBTYPE).
  • if the database type could not be detected then the type is unknown and all operations are exectuted as it would be Microsoft SQL Server
  • Meta

    Properties

    Methods

    Initializations


    Class DataContainer ^

    count, data, datasource, first, last

    add, contains, newWith, paginate, toString, unique
    Represents generic container which holds data. The container offers different functions to manipulate the underlying data. The data is bound by reference and therefore all changes will affect the original source. Ajaxed loads this class automatically so its available everywhere. Example of usage with different datasources:
    
    <%
    'container with an array as datasource
    set dc = (new DataContainer)(array(1, 2, 3))
    
    'container with a dictionary as datasource
    set dc = (new DataContainer)(lib.newDict(1, 2, 3))
    
    'container for a recordset
    set dc = (new DataContainer)(lib.getRS("SELECT * FROM table"))
    %>
    
    After the intantiation its possible to use the different methods on the created DataContainer. Example:
    
    <%
    set dc = (new DataContainer)(array(1, 2, 3))
    'check if a given value exists in the container
    dc.contains(2)
    'its even possible in one line
    ((new DataContainer)(array(1, 2, 3))).contains(2)
    %>
    

    Meta

    Properties

    Methods


    Class Datatable ^

    attributes, col, columnsCount, css, cssClass, customControls, data, fullsearch, fullsearchValue, ID, name, nullSign, onRowCreated, pkColumn, recordLink, recordLinkF, recsPerPage, row, selection, sort, sorting, sql

    draw, newColumn, sortedBy
    Represents a control which uses data based on a SQL query and renders it as a data table. The whole datatable is represented as a html table and contains rows (records) and columns (columns defined in the SQL query). Columns (DatatableColumn instances) must be added to the table. Columns are auto generated if none are defined by the client. Datatable contains the following main features which makes it a very powerful component:
  • only a SQL query is needed as the datasource. All columns which are exposed in the query can be used within the table.
  • supports sorting & pagination
  • full text search can be applied
  • TODO: quick deletion of records
  • TODO: export of the data to all kind of different formats
  • TODO: all user settings (sorting orders, current page, ...) are remembered during the session. This makes bulk editing easier for users.
  • optimized for printing
  • it is loaded with a default style but styles can be adopted to own needs and custom application design
  • uses ajaxed StringBuilder so it works also with large sets of data
  • For better performance and nicer user experience all requests are handled with ajax (using pagePart feature of ajaxed)
  • offers the possibility to change properties during runtime (hide/disable rows, change styles, change data, ...).
  • Full example of a fsimple Datatable which shows all users of an application (columns are auto detected):
    
    <%
    set dt = new Datatable
    set page = new AjaxedPage
    page.draw()
    
    sub init()
        dt.sql = "SELECT * FROM user"
        dt.sort = "firstname"
    end sub
    
    sub callback(a)
        dr.draw()
    end sub
    
    sub main()
        dt.draw()
    end sub
    %>
    
    As you can see in the example its necessary to draw the datatable in the main and the callback sub. Thats needed because all the sorting, paging, etc. is done with AJAX using ajaxed callback feature (pageParts). Setting the properties of the datatable must be done within the pages init() sub (which is executed before callback and main). In most cases its necessary to decide which columns should be used. Therefore columns must be added manually using newColmn() metnod:
    <% dt.newColumn("firstname", "Firstname")%>

    Meta

    Properties

    Methods


    Class DatatableColumn ^

    caption, cssClass, dt, encodeHTML, help, index, link, name, nullValue, onCellCreated, value, valueF
    Represents a column of the Datatable. It is identified by a name (must exist in the datatables SQL query). Use the Datatable.newColumn(name, caption) factory method to add a new column to the datatable. Assigning the column to a variable allows changing further properties.
    Example of adding a column for a database column named firstname and labeling it Firstname. Furthermore it will use the css class colFirstname (we assume an existing Datatable instance dt):
    
    <%
    set c = dt.newColumn("firstname", "Firstname")
    c.cssClass = "colFirstname"
    %>
    

    Meta

    Properties


    Class DatatableRow ^

    attributes, cssClass, disabled, dt, ID, number, PK, selected
    Represents a row in a datatable. Can only be accessed when using the onRowCreated event of the Datatable. When the event is raised its possible to access the current row with the row property of the Datatable. Example of how to mark first 10 records of a datatable as selected using the row's selected property:
    
    <%
    dt.selection = "multiple"
    dt.onRowCreated = "onRow"
    sub onRow(callerDT)
        callerDT.row.selected = callerDT.row.number <= 10
    end sub
    %>
    

    Meta

    Properties


    Class Dropdown ^

    attributes, autoDrawItems, commonFieldText, commonFieldValue, cssClass, datasource, dataTextField, dataValueField, disabled, ID, multiple, multipleSelectionType, name, onItemCreated, selectedValue, size, style, tabIndex, uniqueID, valuesDatasource

    draw, getNew, getNewItem, toString
    represents a HTML-selectbox in an OO-approach.
  • naming and functionallity is based on .NET-control DropdownList
  • easy use with different datasources: recordset, dictionary and array
  • there are 3 different rendering types when using it as a multiple dropdown. e.g. you can render a dropdown where each item has a radiobutton so the user can make only one selection. check multipleSelectionType property for more details
  • to build a new dropdown create a new instance, set the desired properties and use draw() method to render the dropdown on the page. If the output is needed as a string then toString() can be used
  • in most cases you need a dropdown with data from the database. in that case you can use getNew() method which quickly creates a dropdown for you. as it is the default method you can simply use it with
    <% (new Dropdown)("SELECT * FROM table", "name", "selected").toString() %>
  • Example of simply creating a dropdown with all months of a year and the current month selected:
    <% (new Dropdown)(lib.range(1, 12, 1), "month", month(date())).toString() %>
  • Meta

    Properties

    Methods


    Class DropdownItem ^

    attributes, dropdown, index, selected, show, style, text, title, value

    draw
    represents an item of the dropdown

    Meta

    Properties

    Methods


    Class Email ^

    allTo, body, component, componentsOrdered, dispatch, errorMsg, html, mailer, mailServer, mailServerPassword, mailServerUsername, onlyValidEmails, recipients, sendersEmail, sendersName, subject, supportedComponents

    addAttachment, addRecipient, addRecipients, emailName, newWith, quickSend, send
    This class represents an email. It is a generic interface which internally uses a third party component (automatically detected).
  • Create a new instance, set the properties and send or use newWith(template) and create a new instance with a template which will set the body and the subject of the email automatically from the TextTemplate
  • You should send an email whereever you want to send an email in your application despite if you dont know if an email component will be installed.
  • Meta

    Properties

    Methods

    Initializations


    Class JSON ^

    recordsetPaging, toResponse

    escape, toJSON
    Comes up with functionality for JSON (http://json.org) to use within ASP. Correct escaping of characters, generating JSON Grammer out of ASP datatypes and structures Some examples (all use the toJSON() method but as it is the class' default method it can be left out):
    
    <%
    'simple number
    output = (new JSON)("myNum", 2, false)
    'generates {"myNum": 2}
    
    'array with different datatypes
    output = (new JSON)("anArray", array(2, "x", null), true)
    'generates "anArray": [2, "x", null]
    '(note: the last parameter was true, thus no surrounding brackets in the result)
    %>
    

    Meta

    Properties

    Methods


    Class Library ^

    browser, dev, env, fso, live, logger, page, version

    arrayize, contains, detectComponent, error, exec, getFunction, getGUID, getUniqueID, iif, init, newDict, newRecordset, options, path, random, range, requestURL, require, sleep, throwError, URLDecode
    This class holds all general methods used within the library. They are accessible through an already existing instance called lib. It represents the Ajaxed Library itself somehow ;) Thats why e.g. its possible to get the current version of the library using lib.version
  • environment specific configs are loaded when an instance of Library is created (thus its possible to override configs dependent on the environment). just place a sub called envDEV to override configs for the dev environment. envLIVE for the live. Note: The config var must be defined outside the sub in order to work:
  • 
    <%
    'by default we disable the logging
    AJAXED_LOGLEVEL = 0
    sub envDEV()
        'but we enable it on the dev environment
        AJAXED_LOGLEVEL = 1
    end sub
    %>
    

    Meta

    Properties

    Methods


    Class Localization ^

    comma, IP

    locateClient
    Contains all stuff which has to do with Localization. "Localization is the configuration that allows a program to be adaptable to local national-language features." Also stuff about the client can be found in this class e.g. clients IP address (often needed to localize the user)

    Meta

    Properties

    Methods


    Class Logger ^

    colorize, defaultStyle, logfile, logLevel, msgPrefix, path, prefix

    clearLogs, debug, error, info, log, logsOnLevel, warn
    Provides the opportunity to log messages into text files. Logging can be done on different levels:
  • 1 (debug): all kind of debugging messages
  • 2 (info): messages which should inform the developer about something. e.g. Progress of a procedure
  • 4 (warn): messages which warn the developer. e.g. a method is obsolete
  • 8 (error): messages which contain an error
  • Which messages are actually logged can be set with the logLevel property directly or in the config with AJAXED_LOGLEVEL. Simple logging within ajaxed:
    
    <%
    lib.logger.debug("some debug message")
    lib.logger.warn("a warning like e.g. use method A instead of B")
    lib.logger.info("user logged in")
    lib.logger.error("some error happend")
    %>
    
  • Logging is disabled by default
  • Logger supports ascii coloring => log files are easier to read.
  • Its recommended to download e.g. "cygwin" and hook up the log file with "tail -f file.log". This allows you to immediately follow the log and it supports coloring as well.
  • Its also possible to view the changes log files directly in the ajaxed console
  • Logfiles are named after the environment. dev.log and live.log
  • Within the ajaxed library lib.logger holds an instance of a ready-to-use logger
  • Some useful debug messages are already automatically logged within the ajaxed library. e.g. SQL queries, page requestes, ajaxed callbacks, emails, ...
  • Log files can also be found in the ajaxed console.
  • It might be necessary that the logs path has write permission for the IIS user
  • All non-ascii chars (\u0100-\uFFFF) will be converted to its hex notation (e.g. \uF9F9) as most shells cannot display unicode
  • Meta

    Properties

    Methods

    Initializations


    Class MD5 ^



    hash
    Thats a class for MD5 encryption. MD5: Derived from the RSA Data Security, Inc. MD5 Message-Digest Algorithm, as set out in the memo RFC1321. One way encryption! Encryption-code taken from Web Site: http://www.frez.co.uk and modified to a class. Many thanks!

    Meta

    Methods


    Class RSS ^

    debug, description, failed, items, language, link, publishedDate, theCache, timeout, title, url

    addItem, draw, generate, load, loadNew, reflect, setCache
    Reads RSS feeds and gives you the possibility of formating it with xsl or using the items programmatically as objects. Additionally it lets you generate your own feeds.
  • READING: achieved with load() or draw(). Refer to the methods for the supported versions
  • WRITING: achiedved with generate(). Refer to the method for the supported versions
  • If caching should be enabled use the setCache() method. By default caching is off.
  • on draw() caching stores the complete transformed output in the cache
  • on load() caching stores the xml in the cache and parses it out from the cache.
  • Simple example of how to read an RSS feed:
    
    <%
    set r = new RSS
    r.url = "http://somehost.com/somefeed.xml"
    r.load()
    if r.failed then lib.error("could not read feed. could be down or wrong format")
    for each it in r.items
        str.write(r.title & "<br>")
    next
    %>
    

    Meta

    Properties

    Methods


    Class RSSItem ^

    author, category, comments, description, GUID, link, publishedDate, title

    reflect
    used with the RSSReader

    Meta

    Properties

    Methods


    Class StringBuilder ^

    component, supportedComponents

    append, toString, write
    Represents a string builder which handles string concatenation. If a supported stringbuilder COM component can be found it is used and hence the concatenation is much faster than common string concatening.
  • check supported components with the supportedComponents property.
  • you should use it whereever there is a loads of output to be rendered on your page. Its faster than normal concatening.
  • basically just intantiate it and use append() method for appending. In the end use toString() to output your string
  • if there is no component found then it would be faster to directly write the output to the response. This can be achieved using the write() method
  • Best way to use the StringBuilder (always uses the fastest possible method):
    
    <%
    set output = new StringBuilder
    output("some text")
    output("some other text")
    %>
    <%= output.toString() %>
    

    Meta

    Properties

    Methods


    Class StringOperations ^



    arrayToString, ASCIICode, capitalize, change, clone, defuseHTML, divide, end, endsWith, ensureSlash, existsIn, format, getHiddenInput, HTMLEncode, humanize, isAlphabetic, isValidEmail, JSEncode, matching, multiArrayToString, nullIfEmpty, padLeft, padRight, parse, rReplace, shorten, splitValue, SQLSafe, startsWith, stripTags, swapCase, toCharArray, toFloat, toInt, trimComplete, trimEnd, trimStart, trimString, URL, write, writeEnd, writef, writeln
    Collection of various useful string operations. An instance of this class called str is created when loading the page. Thus all methods can easily be accessed using str.methodName

    Meta

    Methods


    Class TestFixture ^

    allEnvs, debug, lineBreak, requestTimeout

    assert, assertEqual, assertHas, assertHasNot, assertInDelta, assertInFile, assertInstanceOf, assertMatch, assertNot, assertNotEqual, assertNothing, assertNotInFile, assertResponse, fail, info, run
    Represents a test fixture which can consist of one ore more tests.
  • Tests must be subs which are named test_1(), test_2(), etc.
  • Call the different assert methods within your tests
  • if you need to debug your failures then turn on the debug property
  • create a setup() sub if you need a procedure which will be called before every test
  • run the fixture with the run() method
  • Example of a simple test (put this in an own file):
    
    <!--#include virtual="/ajaxed/class_TestFixture/testFixture.asp"-->
    <%
    set tf = new TestFixture
    tf.run()
    
    sub test_1()
        tf.assert 1 = 1, "1 is not equal 2"
        'Lets test if our home page works
        tf.assertResponse "/default.asp", empty, "<h1>Welcome</h1>", "Welcome page seems not to work"
    end sub
    %>
    

    Meta

    Properties

    Methods


    Class TextTemplate ^

    cleanParse, content, fileName, placeHolderBegin, placeHolderEnd, UTF8

    add, addVariable, delete, getAllButFirstLine, getFirstLine, returnString, save
    Represents a textbased template which can be used as content for emails, etc. It uses a file and replaces given placeholders with specific values. Placeholders can be common name value pairs or even whole blocks which hold name value pairs and can be duplicated several times. It's possible to create, modify and delete the templates. Example for the usage as an email template (first line of the template is used as subject): This is how a template would look like:
    
    Welcome!
    Dear <<< name >>>,
    Thanks joining us!
    We belive your age must be <<< age | not specified >>>.
    
    The following code is required to us the template above:
    
    <%
    set t = new TextTemplate
    t.filename = "/templateFileName.txt"
    t.add "name", "John Doe"
    email.subject = t.getFirstLine()
    email.body = t.getAllButFirstLine()
    %>
    
    Note: The age placeholder has not been used in the code. For that reason the TextTemplate will return its default value which can be specified after the | (pipe) sign. It can be read as 'display age or "not specified" if no age available'

    Meta

    Properties

    Methods


    Class TextTemplateBlock ^

    items

    addItem, addRS
    Represents a block which is used within a TextTemplate. Blocks are defined with <<< BLOCK NAME >>> ... <<< BLOCKEND NAME >>>. Placeholders may be defined between the begining and the ending of the block. Example of a block
    
    <<< BLOCK DETAILS >>>
    Name: <<< NAME >>>
    <<< BLOCKEND DETAILS >>>
    

    Meta

    Properties

    Methods


    Class Validator ^

    reflectItemPostfix, reflectItemPrefix, valid

    add, getDescription, getErrorSummary, getInvalidData, isInvalid, reflect
    Represents a general validation container which can be used for the validation of business objects or any other kind of validation. It stores invalid fields (e.g. property of a class) with an associated error message (why is the field invalid). The underlying storage is a dictionary.
  • It implements a reflect() method thus it can be used nicely on callbacks. A callback could return a whole validator ;)
  • Example of simple usage:
    
    <%
    set v = new Validator
    if lastname = "" then v.add "lastname", "Lastname cannot be empty"
    if str.parse(age, 0) <= 0 then v.add "age", "Age must be a number and greater than 0"
    if v then
        save()
    else
        str.write(v.getErrorSummary("<ul>", "</ul>", "<li>", "</li>"))
    end if
    %>
    

    Meta

    Properties

    Methods



    Are looking for more support?

    Version 2.1 released1791 days ago