Skip Navigation

Text Only/ Printer-Friendly

Reason Programming 101 Notes

Introduction

  • Pre-reason Systems
  • Sharing Needs
  • Reuse of Code, Reuse of Data
  • Standardization of datatypes across sites

How reason differs from a traditional database

  • Single master table of records vs. separate table for each data type
  • Single table of relationships vs. separate table for each relationship type
  • Can locate record based soley on id vs. needing to know both table and id
  • Automated yet customizable administrative interface
  • Can create and alter datatypes without modification of underlying table structure
  • Maintains a lot of metadata about its data structures
  • Provides a lot of introspection -- easy to ask system how it is set up

The Entity class

  • Entity is like a root object from which everything extends
  • Wraps up a particular record in an object
  • Gives you access to methods that help get more info about record

Types

  • Types are how information in Reason is organized
  • Analagous to a traditional database application's tables
  • Every entity has a type
  • Types are also entities
  • Having types exist as records in DB has some nice effects that we'll see later
  • Common types: page, Image, News item

Analogies to traditional relational database

  • Type --> Table
  • Entity --> Record
  • Demo 1
    • Given an ID, use the entity class to get all the information about that entity.
      • entity data
      • type info
  • Exercise 1
    • Write a script that takes an entity id and a type id. If the entity is of the type, show its name, id, and last modified date, "pray" the entity, and output the name of the type.
    • type ids: 88 (news), 243 (image), 3317 (page)

Sites and Ownership

  • Every entity is owned by a site
  • Sites are entities too
  • Demo 2
    • Extend demo 1 to get info about the site which owns the entity
    • introduce get_owner()
  • Exercise 2
    • Create a script which takes an entity id and shows info about the owner

Relationships

  • A relationship connects two entities in some way
  • Each relationship has a relationship type (Allowable Relationships) that defines what that relationship means
  • What types can be related
  • What direction those types are related to each other in
  • Whether relationships are one-to-many or many-to-many
  • Whether relationships are required
  • From which sides of the relationship the admin interface allows relationship creation
  • Some relationships are handled automatically by Reason:
  • Ownership
  • Archiving
  • Other relationships are created manually by the users
  • Examples: page to image, news to category, page to parent page
  • Analogy to traditional relational database
    • Allowable Relationship --> Relationship Table
  • Demo 3:
    • Extend demo 2 to grab entities that are related to the given entity
  • Exercise 3:
    • Create a script which displays the names of all of the entities that are related via the relationship type "page_to_image"
    • Page id = 119425
    • introduce relationship_id_of()

The Entity Selector

  • A class that gets sets of entities out of the database
  • Handles most of the work of building complex SQL select statements
  • Transforms SQL results into useful entity objects
  • Extends the DB Selector and makes it more abstract and powerful
  • Used for most Reason queries

The DB Selector

  • A generic class which builds up an SQL select query based on parameters provided
  • Used for some unusual queries which Entity Selector doesn't handle
  • Many of the basic Entity Selector functions derive from the DB Selector
  • Demo 4:
    • Select all entities of some type that are owned by some site
    • introduce id_of()
  • Exercise 4:
    • Build a script which can take a site id.
    • if site id given, verify that id belongs to a site and list pages that belong to the site
    • if site id not given, display a list of all Reason sites, which link to page listings for each site

Refining Entity Selectors

  • Sorting
  • Adding relations
  • Setting number
    (these all inherited from DB selector)
  • Demo 5:
    • Sort reverse by name, add some relation, set a count
  • Exercise 5:
    • Sort sites by name, limit pages to 5 most recently modified

Using relationships to define entity selection

  • Entity selector class has add_left_relationship and add_right_relationship methods
  • Directionality matters:
    • Each relationship has a left-side entity and a right-side entity
    • Example: in the page_to_image relationship, the page will always be on the left side and the image will always be on the right
    • When you grab entities across a relationship, you need to know both the relationship type and the direction
  • Demo 6:
    • Only show sites that are of a particular site type
  • Exercise 6:
    • For each page on the selected site, list images associated with the page
    • hint: use show_image() to build img tags

Minisite Framework

  • The Reason front end is 99% based on the minisite framework
  • Exceptions: News and Athletics
  • Pages are arranged hierarchically via the minisite_page_parent relationship
    • Home page has minisite_page_parent relationship with itself
  • Each page has title, content, etc.
  • Demo & Exercise 7: Create a page and play around with position in hierarchy

Page Types

  • Each page also has a page_type
  • When a page is displayed Reason looks up the page_type to see what modules to place on page
    • Examples of modules: Navigation, Content, Page Title, News, Events, Images, etc.
    • Modules can be placed on any page
  • Demo & Exercise 8:
    • Create a new page type using existing modules

Modules

  • Modules extend the Default Module class
  • Modules are instantiated, initialized, and run
  • Modules are what allows code to be reused in multiple places across Carleton's site
  • Demo 9:
    • Write a module that displays the page's relationships
  • Exercise 9:
    • Write a module that displays images related to the current page
    • Create a page type that uses that module

Backend Editing Framework: Content Managers

  • Content Managers automatically generate forms for creating & editing entities
  • By default they use the type definition to build the form elements and write to the db
  • You can customize how particular types are edited by creating new content managers
  • Content Managers are one use of Disco forms
    • Disco provides a framework for form handling
  • Demo 10
    • Create a content manager and do some random trivial change to the form
    • Options:
      • Add comments
      • Change types
      • Change display names
      • Set values
      • Remove
  • Exercise 10
    • Create a content manager for the Book type and make some changes