Permalink
Browse files

travel docs

  • Loading branch information...
1 parent dde0b5a commit 3357b37a4245ae4d8eccd18f578ca456f3879e41 @ethn ethn committed Jul 23, 2015
Showing 423 changed files with 145,243 additions and 44 deletions.
View
Oops, something went wrong.
View
Binary file not shown.
Binary file not shown.
View
Binary file not shown.
View
@@ -0,0 +1,9 @@
+card/lib/**/*.rb \
+wagn/lib/**/*.rb \
+wagn/rails/**/*.rb \
+decko-rails/lib/**/*.rb \
+../sites/core-dev/tmp/set*/**/*.rb - \
+*.rdoc \
+card/GPL \
+card/LICENSE \
+card/VERSION
View
@@ -1,7 +1,9 @@
=Thinking about contributing to Wagn?
-Thank you!
+Welcome! And thanks for taking the first step.
-In coming months we plan to work to make the process of contributing and entering the Wagn developer community as rewarding an experience as possible. In the meantime, please be vocal about any way we can help.
+We want to make contributing to Wagn as rewarding an experience as possible. Please jump in, and ask away for help.
+
+FIXME - contact routes here (support ticket, google group, etc. slack?)
==Basics
The Wagn team makes heavy use of {GitHub's pull request system}[https://help.github.com/articles/using-pull-requests]. If you're not familiar with pull requests, that's the best place to start.
@@ -0,0 +1,61 @@
+==Is this doc for you?
+
+This page offers a Developer's introduction to the Wagn code base and how to customize it for your own needs. it assumes you're a ruby developer or, at least, someone who does not fear ruby code.
+
+It also assumes that you've experimented with Wagn enough to have some familiarity with the basics (cards, types, rules, etc.) <b>If you have no idea what a card is, you may find it helpful to begin at {http://wagn.org Wagn.org}</b> to get a sense of what Wagn's all about.
+
+And, finally, it assumes you're looking at it from a docs site (ie, NOT GitHub). The page is peppered with links; if they're breaking, try FIXME - (give links here).
+
+
+==Intro
+
+If you're new to Wagn development, you may be trying to wrap your head around <b>whether Wagn is an application or a development framework. It's both.</b>
+
+When you install a new Wagn, you get a lot more out of the box than you would with a typical dev framework; you have a working website right away. We often call Wagn sites "decks" (as in groups of cards.) After seeding your deck (with `wagn seed`), you will have lots of things built in: account handling, edit histories, default layouts, CSS, etc. In other words: you have a basic application.
+
+But a newly seeded deck is just a starting point. <b>Wagn is a development framework in which you start <i>in the middle of things</i> rather than from scratch</b>. Seeding is a bit of a headstart, and it means that designers, developers, and content creators can start working in parallel on day 1. But the seeded cards don't determine what you can build with Wagn; you can add things, you can remove things... In fact, we want to make it possible to build pretty much whatever you want.
+
+
+==Ruby on Rails Descendant
+
+It's likely that many folks reading this are Ruby-on-Rails developers. Wagn owes a great deal of debt to the Rails community, both in terms of code and in stylistic guidance. Rails developers will find lots of familiar patterns in Wagn, but we should be clear: <b>Wagn development is different</b>.
+
+Typical Rails development will involve creating lots of new models, views, and controllers. Wagn mod developers do create lots of views (though they're quite different from Rails views), but we never create new models or controllers. In the Wagn gem there is one controller ({CardController}), one main model ({Card}), and several other models to optimize the Card model and track its history ({Card::Reference}, {Card::Act}, {Card::Action}, and {Card::Change}).
+
+Most Wagn developers never have to give the controller or any model besides Card any thought. The equivalent of creating a new model is configuring a new Set of cards. The equivalent of creating new actions on controllers is creating new events that are conditionally triggeres for a Set of cards.
+
+So, as a starting place it's probably <b>best to think of Wagn not as a Rails app but a Rails descendant</b>. Rails development experience is definitely a plus in getting to know Wagn, but Wagn offers a new architecture, and lot of new possibilities.
+
+
+==MoFoS Architecture
+
+Wagn is not, like Rails, an implementation of the "MVC" (Model-View-Controller) architectural pattern, or any well-established pattern, really. Instead, we like to think that we're the first instance of a new pattern that we call _MoFoS_.
+
+MoFoS stands for "Model-Formats-Sets". It's intentional that the word "Model" alone is singular; the idea is that there is just one primary data model (Card, in Wagn's case), and that this model is given meaning by subdividing into multiple configurable Sets and made productive by connecting cards to multiplfe Formats.
+
+_Sets_ are a central organizing concept for both Wagneers and Wagn developers. If you've edited Rules through a card toolbar in any Wagn deck, you will have encountered Sets. For example, imagine you're on a User card named "Henry Tai", and you decide to edit its structure. When you edit its rule, you will be prompted to choose the Set of cards to which the rule applies, eg:
+
+* Just "Henry Tai"
+* All Users
+* All Cards
+
+Depending on which Set you choose, the Rule in question will be applied to a specific group of cards. This same general pattern occurs in Wagn code: <b>code rules (methods) are organized under the Set of cards to which they apply.</b>
+
+The great power of MoFoS is that, unlike in MVC, code rules (and data rules) can be as narrow or specific as desired. In MVC, it's challenging to create rules that apply to multiple models or single instances of a model; in MoFoS, this is very fluid.
+
+
+==Mods
+
+A Wagn Mod is a discrete piece of Wagn functionality
+
+chunk format layout set set_pattern spec file lib
+
+===Set Patterns
+
+===Formats
+If there are rules on multiple sets of which a given card is a member, then precedence is determined by Set Pattern. For example, the above three sets have the Self pattern (always a single card), the Type pattern (here "User"), and the All pattern. Set Patterns have a fixed override order, beginning with a specific model instance and ending with the Set of all cards.
+
+While Set Patterns have a clean hierarchy, sets themselves do not. This means traditional class hierarchies do not suffice for representing Set code. A Wagn example: Say A+address is a "Phrase" card and B+address is a "Basic" card. This implies that the Set of "cards ending in +address" cannot safely inherit rules from any given type Set.
+
+This organizing concept turns out to be remarkably
+
View
@@ -2,9 +2,14 @@
==Basics
-Wagn is an open web platform for building coherent web systems.
+Wagn is serious web development made fun.
+
+"Wagneers" have used Wagn to create open community sites, private knowledge management sites, public proposal submission sites with private back-ends for review, project management systems, wikis, blogs, journals, forums, and more.
+
+Install Wagn, open a webpage, and get started. With Wagn's wiki-inspired building blocks, you can collaborate from day one on content, design, and structure create elegant web systems on the fly. And ruby developers can take these creations even further with Wagn's development framework. Wagn's innovative Mods API supports boundless creativity while integrating seamlessly with structures created on the site.
+
+FIXME - add cldstr link
-Using simple wiki-inspired building blocks called cards, "Wagneers" construct sites ranging from simple content managers to custom project trackers to fully integrated web suites.
==System Requirements
@@ -89,6 +94,14 @@ First check the Wagn version of your existing site.
First update your Wagn to version 1.10 via the old update mechanisms, and then follow the directions above.
+==Developing
+
+Wagn allows for deep collaboration and integration between "wagneers" (who organize data via a wagn site) and software developers.
+
+Learn more at "GETTING STARTED - Developers"
+FIXME - link
+
+
==More Resources
View
@@ -12,6 +12,7 @@ task :release do
system %(git tag -a v#{version} -m "Wagn Version #{version}"; git push --tags wagn)
end
+
def version
File.open(File.expand_path( '../card/VERSION', __FILE__ )).read.chomp
end
View
@@ -1,7 +1,19 @@
# -*- encoding : utf-8 -*-
+
Object.send :remove_const, :Card if Object.send(:const_defined?, :Card)
+
+=begin
+This documentation is intended for developers who want to understand:
+
+a. how ruby Card objects work and
+b. how to extend them.
+
+It assumes that you've already read the introductory text in {file:GETTING STARTED - Developers.rdoc}.
+
+=end
+
class Card < ActiveRecord::Base
require_dependency 'card/active_record_ext'
require_dependency 'card/codename'
@@ -2,34 +2,36 @@
require 'uri/common'
-# A chunk is a pattern of text that can be protected
-# and interrogated by a format. Each Chunk class has a
-# +pattern+ that states what sort of text it matches.
-# Chunks are initalized by passing in the result of a
-# match by its pattern.
+
class Card
+
+ # A chunk is a pattern of text that can be protected
+ # and interrogated by a format. Each Chunk class has a
+ # +pattern+ that states what sort of text it matches.
+ # Chunks are initalized by passing in the result of a
+ # match by its pattern.
module Chunk
mattr_accessor :raw_list, :prefix_regexp_by_list, :prefix_map
@@raw_list, @@prefix_regexp_by_list, @@prefix_map = {}, {}, {}
-
+
class << self
def register_class klass, hash
klass.config = hash.merge :class => klass
- prefix_index = hash[:idx_char] || :default # this is gross and needs to be moved out.
+ prefix_index = hash[:idx_char] || :default # this is gross and needs to be moved out.
prefix_map[prefix_index] = klass.config
end
-
+
def register_list key, list
raw_list[key] = list
end
-
+
def find_class_by_prefix prefix
config = prefix_map[ prefix[0,1] ] || prefix_map[ prefix[-1,1] ] || prefix_map[:default]
#prefix identified by first character, last character, or default. a little ugly...
config[:class]
end
-
+
def get_prefix_regexp chunk_list_key
prefix_regexp_by_list[chunk_list_key] ||= begin
chunk_types = raw_list[chunk_list_key].map { |chunkname| const_get chunkname }
@@ -41,17 +43,17 @@ def get_prefix_regexp chunk_list_key
end
end
-
-
+
+
#not sure whether this is best place. Could really happen almost anywhere (even before chunk classes are loaded).
register_list :default, [ :URI, :HostURI, :EmailURI, :EscapedLiteral, :Include, :Link ]
register_list :references, [ :EscapedLiteral, :Include, :Link ]
register_list :inclusion_only, [ :Include ]
-
+
class Abstract
class_attribute :config
attr_reader :text, :process_chunk
-
+
class << self
def full_match content, prefix=nil
# warn "attempting full match on #{content}. class = #{self}"
@@ -61,7 +63,7 @@ def full_match content, prefix=nil
def full_re prefix
config[:full_re]
end
-
+
def context_ok? content, chunk_start
true
end
@@ -74,15 +76,15 @@ def initialize match, content
interpret match, content
self
end
-
+
def interpret match_string, content, params
Rails.logger.info "no #interpret method found for chunk class: #{self.class}"
end
-
+
def format
@content.format
end
-
+
def card
@content.card
end
@@ -10,7 +10,7 @@ module Set
=begin
- A "Set" is a group of cards to which "Rules" may be applied. Sets can be as specific as
+ A "Set" is a group of Cards to which "Rules" may be applied. Sets can be as specific as
a single card, as general as all cards, or anywhere in between.
Rules take two main forms: card rules and code rules.
View
@@ -2,10 +2,11 @@
require 'active_support/core_ext/numeric/time'
-CARD_GEM_ROOT = File.expand_path('../..', __FILE__)
module Cardio
+ CARD_GEM_ROOT = File.expand_path('../..', __FILE__)
+
ActiveSupport.on_load :card do
if Card.count > 0
Card::Loader.load_mods
@@ -1,3 +1,7 @@
+
+
+
+
RuleSQL = %{
select rules.id as rule_id, settings.id as setting_id, sets.id as set_id, sets.left_id as anchor_id, sets.right_id as set_tag_id
from cards rules
@@ -74,7 +74,7 @@ def authenticate_by_token val
event :set_default_salt, :on=>:create, :before=>:process_subcards do
salt = Digest::SHA1.hexdigest "--#{Time.now.to_s}--"
Env[:salt] = salt # HACK!!! need viable mechanism to get this to password
- subcards["+#{Card[:salt].name}"] ||= {:content => salt }
+ subcards["+#{Card[:salt].name}"] ||= { :content => salt }
end
event :set_default_status, :on=>:create, :before=>:process_subcards do
Oops, something went wrong.

0 comments on commit 3357b37

Please sign in to comment.