We haven't yet banged out details about how Module installs and uninstalls will work. We suspect there may be some similarities to rails migrations. But it's clear that it will make considerable use of the Card model.
The Card class inherits from ActiveRecord. For example, you can instantiate and save a card to the database as follows:
my_card = Card.new :name => 'Bazooka', :type=>'Phrase', :content=>'Boom' my_card.save
Or you can do...
Card.create :name => 'Bazooka', :type=>'Phrase', :content=>'Boom'
...to do both at once. That's all pretty standard Rails fare. And it may or may not be part of the blessed api, (see blessed vs. unblessed below) but it's important for understanding how things are put together.
One part of the standard ActiveRecord api that will not be blessed is the #find method. Instead, you will be able to use either #fetch or #search to retrieve cards, both of which avail you of cards from the cache (unlike #find, which is strictly a SQL wrapper).
The #fetch method is for retrieving single cards. It looks something like this:
Card.fetch cardname, opts={}
the most import "opt" is :skip_virtual, which makes it so that #fetch will not return virtual cards -- only cards that are actually in the database. You can also combine #fetch with #new as follows:
Card.fetch 'Bazooka', :new=>{ :type=>'Phrase', :content=>'Boom'}
The :new opts will be passed on to #new if the card does not already exist. Those methods will almost certainly be blessed, as will the #search method:
Card.search wql eg. cards = Card.search :type=>'User'
The card objects retrieved by #fetch (singly) and #search (plurally) have typical ActiveRecord accessors, the most frequently used of which (and some of the few initially blessed) will be name, type*, and content:
my_card = Card.fetch 'Monkey Tail' my_card.content = 'long and furry' # this is the actual database content for this card and may be overridden by *structure settings or custom views my_card.type = :phrase # all code references to card names should use codenames, which are signified with ruby Symbols. this will also be the datatype returned by #type. However #type= will also be able to interpret strings (cardnames) and numbers(card ids) my_card.save! # as with normal ActiveRecord models, save will commit any changes to the database. We will be releasing lots more API for managing validations and tracking my_card.delete # Unlike ActiveRecord's #destroy, #delete doesn't actually remove the card, it just puts it in the trash.
We anticipate that eventually part of the setup process for a module (particularly those not part of the core) will be creating a "Module" card ("Module" being a cardtype), and that this card would serve for administering the module. That might not be there right out of the gate..
The dominant use of the model api is when creating new views or actions. But it is also possible to extend the basic card model with methods that in apply only the set in question:
#file: lib/wagn/set/type/html.rb
def clean_html? false end
The above is a real code sample that turns off html cleaning for HTML cards (which is why you should only allow administrators to edit them).