Documentation

These are the basic functions of newLISP on Rockets. Additional documentation and tutorials are coming soon.

Quick setup guide for installing Rockets on a new Linux system

If you get the error "Cannot find crypto library"




DEPENDENCIES


  • css/boostrap.css - Bootstrap framework CSS file
  • css/bootstrap-responsive.css - Bootstrap responsive framework (for mobile devices)
  • css/datepicker.css - For calendar dropdowns
  • js/jquery-1.8.2.min.js - jQuery (minimum version required)
  • js/bootstrap.min.js - Bootstrap Javascript
  • js/boostrap-datepicker.js - For calendar dropdowns



    GLOBAL VARIABLES


  • $ROCKETS_VERSION - current version of Rockets
  • $MAX_POST_LENGTH - maximum size of data you are allowed to POST
  • $BASE_PATH - the absolute path for the installation (default is /)
  • $PARTIAL_PATH - the relative path for when using (display-partial) (default is "partials")



    BASIC FUNCTIONS


    Function: (benchmark-result)


    Usage: (benchmark-result)

    Returns: displays the text: "Rendered in ## milliseconds. Used ## KB of memory, ## for LISP cells"


    Function: (start-div)


    Usage: (start-div "Div class name")

    Returns: Starts an HTML <DIV> with a given class name


    Function: (end-div)


    Usage: (end-div)

    Returns: Closes off an HTML <DIV>


    Function: (format-for-web)


    Usage: (format-for-web "string of text")

    Returns: Takes a string of text, for example a post full of data including carriage returns and
    line feeds, and returns a string that can be used with (display) or (displayln)
    Note: All HTML code is removed (< and > translated to & lt ; and & gt ; respectively) to avoid
    cross-site scripting issues. URLs are transformed into clickable links. Some UBB code is also
    translated, for example bold, italic, underline, and code tags.


    Function: (force-parameters)


    Usage: (force-parameters int-number-of-parameters "string containing spaces")

    Example: (force-parameters 1 "First Word Only Returned")
    Returns: Takes a string containing spaces and returns only the number of parameters provided
    Use this in conjunction with ($GET) and ($POST) to eliminate SQL injection attempts



    DISPLAY FUNCTIONS


    Function: (display-header)


    Usage: (display-header "Optional page title" "optional-css-file")

    Returns: Prints all the opening page HTML, such as page title, meta tags, and CSS
    Note: Only one optional css file can be included for now. The .css extension is not necessary.


    Function: (display-navbar)


    Usage: (display-header "Site name" '(list of menus) "page-to-go-for-signing-in" true "red")

    Returns: Prints the top navigation bar with menus and form for signing in. Also,
    calling this function also sets up the main <div> container for the whole page.
    Note: The .lsp extension is added automatically to page-to-go-for-signing-in
    Note: The optional "true" is to make the theme of the navigation bar regular colors instead of inverse (black)
    Note: The optional "red" is to add a thin stripe at the end of the navigation bar of a particular color.


    Function: (display-partial)


    Usage: (display-partial "partial-file-name")

    Returns: Loads the instructions in the file "partial-file-name" in the $PARTIAL_PATH subdirectory
    Note: The ".lsp" extension is added automatically.


    Function: (display-footer)


    Usage: (display-footer "Optional Company Name" "Optional Javascript string")

    Returns: Prints the footer with benchmark result. Also loads Javascript libraries.
    Example: (display-footer "JetCondo" "$(document).ready(function() { $(\"#weather\").load(\"weather-widget.html\"); });")
    Note: You do not need to add <script></script> to the optional Javascript, it will be added automatically


    Function: (display-image)


    Usage: (display-image "imagename.jpg" int-width int-height)

    Example: (display-image "rocket.jpg" 200 100)
    Returns: Displays an image from the default /images/ subdirectory. Width and height are optional


    Function: (display-paging-links)


    Usage: (display-paging-links int-start-page int-total-pages int-current-page "page-url" "str-parameters")

    Example: (display-paging-links 1 99 2 "rockets-main" "t=blogposts")
    Returns: Displays a list of clickable paging links, in this example from page 1 to 99, current page 2
    The "page-url" (.lsp extension added automatically) is the page that displays the content


    Function: (display-success)


    Usage: (display-success "Congratulations on your success!")

    Returns: Displays a success text in a light green box that can be dismissed by clicking the "X" button.


    Function: (display-warning)


    Usage: (display-warning "Warning: this is warning text!")

    Returns: Displays a warning in a light yellow box that can be dismissed by clicking the "X" button.


    Function: (display-error)


    Usage: (display-error "Error: this is error text!")

    Returns: Displays a warning in a light red box that can be dismissed by clicking the "X" button.


    Function: (display-h1)


    Usage: (display-h1 "String to display as header")

    Returns: Displays the string bracketed by <h1> and </h1>"


    Function: (display-h2)


    Usage: (display-h2 "String to display as header")

    Returns: Displays the string bracketed by <h2> and </h2>"


    Function: (display-h3)


    Usage: (display-h3 "String to display as header")

    Returns: Displays the string bracketed by <h3> and </h3>"


    Function: (display-h4)


    Usage: (display-h4 "String to display as header")

    Returns: Displays the string bracketed by <h4> and </h4>"


    Function: (display-h5)


    Usage: (display-h5 "String to display as header")

    Returns: Displays the string bracketed by <h5> and </h5>"


    Function: (display-page)


    Usage: (display-page)

    Returns: Displays the current page and exits. This should normally be the last command on any page
    written in newLISP on Rockets.



    PAGE HANDLING


    Function: (page-redirect)


    Usage: (page-redirect "page-to-redirect-to" "p=optional-parameters")

    Loads a new URL immediately when executed. The current page will not be displayed to the user.
    Note: You can add optional parameters to the redirected page.
    Note: The ".lsp" extension is optional and will be added automatically if not entered.



    COOKIE HANDLING


    Function: ($COOKIES)


    Usage: ($COOKIES "optional cookie name")

    Returns: With no argument, returns a list of all active cookies and their values in the environment.
    When "optional cookie name" is specified, returns the value of that cookie.


    Function: (set-cookie)


    Usage: (set-cookie "cookie name" "cookie value" cookie-expiry-date)

    Returns: Sets a cookie. Due to the nature of HTML, it will not actually take effect until
    the next page is loaded. Cookie expiry date should be in the format of a newLISP numeric
    date value, so to pass in a human-readable date, use something like: (date-value 2013 2 28)
    for cookie-expiry-date


    Function: (delete-cookie)


    Usage: (delete-cookie "cookie name")

    Returns: Deletes a cookie. Due to the nature of HTML, it will not actually take effect until
    the next page is loaded.



    GET AND POST FUNCTIONS


    Function: ($GET)


    Usage: ($GET "optional key name")

    Returns: ($GET) on its own returns a list of all key/value pairs from the current URL.
    Optional: ($GET "key name") returns the value for that particular key name.
    Note: You can retrieve multiple values for the same key name by appending [] to the key name.
    Example: URL is "page.lsp?name[]=a&name[]=b", calling ($GET "name[]") will return ("a" "b")


    Function: ($POST)


    Usage: ($POST "optional key name")

    Returns: ($POST) on its own returns a list of all key/value pairs from the page's POST data.
    Optional: ($POST "key name") returns the value for that particular key name.
    Note: You can retrieve multiple values for the same key name by appending [] to the key name.
    Example: POST data contains "name[]=a name[]=b", calling ($POST "name[]") will return ("a" "b")



    DATABASE FUNCTIONS


    Function: (open-database)


    Usage: (open-database "database name")

    Returns: Opens a SQLite3 database. A ".db" extension will be added automatically to the name.
    Note: Only one database can be open at a time. You will need to close one database to open another.


    Function: (close-database)


    Usage: (open-database)

    Returns: Closes the currently open database.


    Function: (query)


    Usage: (query "SQL text")

    This function sends a straight SQL query to the currently open database


    Function: (create-record)


    Usage: (create-record "Table Name" ColumnName1 ColumnName2 ColumnName3 ...)

    Returns: true if creation was successful, otherwise displays the SQL error
    The way this works it that your variable names need to be the same as the column names
    in the database. Enforcing this makes the code simpler and easier to read. Set the values
    before calling (create-record). When it is called, the values of each column will be set in a
    new record in the database.
    Note: Variables need to be either integers or strings, depending on the type of column.
    Note: Date columns need to be strings using the SQL Date format: "YYYY-MM-DD HH:MM:SS.000"


    Function: (update-record)


    Usage: (update-record "Table Name" ConditionColumn ColumnName1 ColumnName2 ColumnName3 ...)

    Returns: true if update was successful, otherwise displays the SQL error
    The way this works it that your variable names need to be the same as the column names
    in the database. Enforcing this makes the code simpler and easier to read. Set the values
    before calling (update-record). When it is called, the values of each column will be set to those values.
    Note: The variable "ConditionColumn" will check to see if the column equals that value
    Example: (update-record "Posts" Id Subject Content) will update the Subject and Content columns
    for all records where Id is equal to the value of the variable Id.
    Note: Variables need to be either integers or strings, depending on the type of column.
    Note: Date columns need to be strings using the SQL Date format: "YYYY-MM-DD HH:MM:SS.000"


    Function: (delete-record)


    Usage: (delete-record "Table Name" ColumnName1)

    Returns: true if deletion was successful, otherwise displays the SQL error
    The variable ColumnName1 needs to be assigned a value that will be checked to qualify the deletion
    Example: (set 'Email "bob@bob.com") (delete-record "Posts" Email) will delete all records where
    the column name "Email" is equal to "bob@bob.com".
    Note: Variables need to be either integers or strings, depending on the type of column.
    Note: Date columns need to be strings using the SQL Date format: "YYYY-MM-DD HH:MM:SS.000"


    Function: (get-record)


    Usage: (get-record "Table Name" ColumnName1)

    Returns: A list of all values for the record if successful, otherwise displays the SQL error
    The variable ColumnName1 needs to be assigned a value that will be checked to qualify the query
    Example: (set 'Email "bob@bob.com") (get-record "Posts" Email) will retrieve all records where
    the column name "Email" is equal to "bob@bob.com".
    Note: Variables need to be either integers or strings, depending on the type of column.
    Note: Date columns need to be strings using the SQL Date format: "YYYY-MM-DD HH:MM:SS.000"



    DATA CONVERSION FUNCTIONS


    Function: (convert-json-to-list)


    Usage: (convert-json-to-list "string of JSON input)

    Returns: A nested list in native newLISP list format in the same structure as the JSON string
    Note: You will still need to define your own functions to retrieve individual data elements
    from the list using (ref) or (ref-all)



    FORM AND TABLE FUNCTIONS


    Function: (display-button)


    Usage: (display-button "Button Title" "page-to-link")

    Returns: Displays a normal button that when clicked, loads the linked page.
    Note: The .lsp extension is optional. If it is not entered, it will be added automatically


    Function: (display-button-green)


    Usage: (display-button-green "Button Title" "page-to-link")

    Returns: Displays a green button that when clicked, loads the linked page.
    Note: The .lsp extension is optional. If it is not entered, it will be added automatically


    Function: (display-button-red)


    Usage: (display-button-red "Button Title" "page-to-link")

    Returns: Displays a red button that when clicked, loads the linked page.
    Note: The .lsp extension is optional. If it is not entered, it will be added automatically


    Function: (display-post-box)


    Usage: (display-post-box "Title" "Form Name" "page-to-submit" "Subject Line ID" "Postbox ID" "Submit Button Text" "optional linkback value" "optional text to pre-populate subject line" "optional text to pre-populate post box" "optional hidden value" bool-include-poll)

    Returns: Displays a form with a subject line and a text box, and a submit button.
    The form will enter information into POST and redirect to "page-to-submit.lsp" when Submit is clicked.
    Note: The .lsp extension is optional. If it is not entered, it will be added automatically.
    Note: You can pre-populate the post box (for example, for editing an existing post) by adding the last two optional parameters.
    Note: You can hide the Subject Line text box by simply entering nil (no quotes) as the subject line.
    Note: The "optional linkback value" parameter sets a hidden field named "linkbackid" in the form and sets it to that value.
    Note: I've added another "optional hidden value" that sets a hidden field named "optionalhidden" in the form and sets it to that value.
    If this becomes a trend, I might just turn hidden values into a list, which would be cleaner, but we'll leave it for now.
    This is useful for when you want the page that is called via the submit button to remember the Id # of, for example,
    which post you were editing or just added.
    Note: The final option "true" will add a poll option to the post box display.


    Function: (form-datepicker)


    Usage: (form-datepicker "Description text" "form-item-name" "form-initial-value" "form-id")

    Example: (form-datepicker "Enter a date" "date" "03-16-2072" "dp1")
    Returns: Displays a date field with a dropdown calendar when the user clicks on the field.
    Note: Requires js/boostrap-datepicker.js and css/datepicker.css to work


    Function: (display-table)


    Usage: (display-table list-of-headers nested-list-of-data "optional form styling" '((optional) (nested) (list) (of) (links)))

    Example: (display-table '("First" "Last" "Email") '(("Joe" "McBain" "joe@joe.com") ("Bob" "McBain" "bob@bob.com")) "striped")
    Returns: Displays a table with headers. If no headers are provided (entered as nil) they will not display
    Note: Styling options are as follows:
    striped - alternates rows in grey
    bordered - adds borders and rounded corners to the table
    hover - enables hover state on table rows when mousing over
    condensed - more condensed style of table



    SOCIAL MEDIA, EMAIL AND RSS FUNCTIONS


    Function: (twitter-search)


    Usage: (twitter-search "Key words" 10)

    Returns: Displays the results of a Twitter search for the key words or phrases entered.
    Optional: Add an integer to specify the maximum number of items to show
    Note: Twitter has changed their API and this function (which used the older, public API) no longer works. I am working on a replacement.


    Function: (send-mail)


    Usage: (send-mail "to@address.com" "from@address.com" "Real Sender Name" "Subject line" "Body text")

    Returns: Sends email to any address from any address. To avoid getting caught in spam
    filters, use a valid From: email address with the same domain as your web site.
    Note: Using this function requires that sendmail is installed on your system.
    Install sendmail using the Linux (Ubuntu or Debian) command "sudo apt-get install sendmail"
    Note: This function sets the appropriate email headers automatically.


    Function: (get-fields-from-rss)


    Usage: (get-fields-from-rss (xml-parse (get-url "http://rss.feed.address") '("List" "of" "field" "names))

    Returns: Returns a nested list of field values, one for each item in the RSS feed.
    Note: The input format is a list formed by the function (xml-parse (get-url "http://rss.feed.address")
    which is a built-in function of newLISP. This list is fed directly into (get-fields-from-rss).
    Example: (set 'rss-result (xml-parse (get-url "http://penny-arcade.com/feed")))
    (set 'field-result (get-fields-from-rss rss-result '("title" "author" "link")))
    Returns: (("News Post: The Book Of Divine Wisdom" "tycho@penny-arcade.com (Tycho)" "http://penny-arcade.com/2013/01/25/the-book-of-divine-wisdom1")
    ("News Post: So many games!" "gabe@penny-arcade.com (Gabe)" "http://penny-arcade.com/2013/01/25/so-many-games")
    ...etc ... )
    Note: If the field is not found in the RSS feed, (get-fields-from-rss) returns "nil" in that spot instead.