User Settings

Frontier provided a way to let you make settings that would be in common for rendering all your Web sites (unless overridden by a setting within a site). For example, if you know that in a lot of different sites you’d like to say “apple” as a shortcut for “http://www.apple.com” in links, it seems silly to make you redefine this in a #glossary hash for every source folder. So you need a place where you can define “apple” to mean “http://www.apple.com” just once, and have this definition available in any page in any Web site you render.

To handle the need for such user settings, RubyFrontier provides the following mechanism. You provide a file — the user.rb file. (It doesn’t actually have to be named user.rb, but that’s the convention and that’s what I’m going to call it.) You tell RubyFrontier where it is by choosing RubyFrontier > Locate User.rb File. From then on, RubyFrontier remembers where this file is (on this computer).

Whenever you give a RubyFrontier command, such as Publish Page, as RubyFrontier is loading all the files where its code is kept, it loads user.rb last. This means that user.rb is your chance to add code to the RubyFrontier command’s Ruby world.

When file user.rb is loaded, here are the sorts of thing it can do:

• Supply a user glossary. If user.rb defines a class method glossary() of a module UserLand::User, that method will be called. It should return a hash of key-value pairs to be used in links; the key should be the string you want to use in the href attribute of a link, and the value should be the URL you want substituted for that key. This hash will be melded into the "glossary" hash formed from any #glossary.yaml files encountered as RubyFrontier walks up the hierarchy, and thus will be available during glossary expansion.

  How you structure the glossary() method is up to you; here’s how I like to do it:

    module UserLand::User
      def self.glossary
        s = <<END
    Frontier
    http://frontier.userland.com
    thebookontheweb
    http://pages.sbcglobal.net/mattneub/frontierDef/ch00.html
    END
        Hash[*s.split("\n")]
      end
    end
  

• Supply outline renderers. If user.rb defines any subclasses of SuperRenderer within a module UserLand::Renderers, those classes will be available as outline renderers (that is, the name of such a class can be used as the value of the :renderoutlinewith directive).

• Inject code into RubyFrontier. A typical use would be that you find yourself needing to keep a utility method in the #tools folder of more than one source folder; you can save yourself the trouble and keep it in user.rb instead. For example, if user.rb defines an instance method of UserLand::Html::PageMaker, then that method can be conveniently called from a macro by using the html. prefix (in accordance with the rules of macro scoping).

  But you can go further. Since user.rb is loaded after the entirety of longestJourney.rb and the various other files it requires, you can actually overshadow RubyFrontier’s own native code if you so desire. This was always a huge problem with Frontier: it wasn’t object-oriented, so it was difficult to overshadow the built-in code with your own, and if you modified the built-in code directly (as I did with many handlers, especially among the html verbs) you risked losing your modifications when you updated the database. With Ruby, however, it’s simple; if you want to open up a RubyFrontier class and mess with it in user.rb, you can. And your changes won’t be directly tromped on when you download an updated version of the RubyFrontier bundle (because your changes are not in the RubyFrontier bundle).

Note concerning the “user templates”: Frontier had a mechanism of “user templates”; any templates kept in the user table could be referred to by name in any site. RubyFrontier imitates this only to the extent of including two “user templates” that can be referred to by name. But they are actually inside the RubyFrontier bundle and so the user templates mechanism is not really open to your use, unless you want to reach right inside the RubyFrontier bundle and put additional templates in there. In future, if there is demand, I am certainly open to restoring a more convenient user templates mechanism; but up to now I have not done so because I haven’t felt the need for it.