SOOJS and WebStorm setup

WebStorm IDE with SOOJS Templates.   As a quick refresher, SOOJS is a simple object-oriented pattern for JavaScript development. And WebStorm is simply the world’s best IDE for JavaScript.

File Template Setup

1. Install WebStorm (seems obvious enough)
2. Install SOOJS File Templates
   • File / Import Settings: SOOJS-WS-FileTemplates.jar (unzip first)

That’s it. Wow, that was easy. Now you have the SOOJS File Templates. NOTE: The file templates here may be old. As changes are made they can be found in the GIT repository. The current direct link to the settings file is: HERE.

More Setup…

These are totally additional setup instructions. I will include my entire WebStorm settings file in this. This setup file has key mappings, and fonts, etc. Import to a new WebStorm build to jumpstart things, but once you have a nice solid WebStorm environment, I’d use the link above to only pull in the templates. IDE Settings File

WebStormSettings.jar (unzip first)

A Blank Project Template

Git Project (clone and start a new project from this one)

read more

Now: Elegant Clock and Weather (2013)

I have been interested in clocks and weather applications for quite some time. Due to that I have a fair number of sketches and investigations into what make these things useful. For the last year or so I have been considering an attempt at some kind of weather presentation and a month or so ago I finally bit the bullet and started official designs.

An interesting thing happened along the way to the app store…

Now represents a 25-foot interface. In this design I decided to work on imparting meaningful information as simply and elegantly as possible. With no shadows, blends, or extraneous graphical elements the interface looks at home in any setting. This became more of a dashboard of current information than about weather presentation — though there are hints at a few concepts I have about weather to be found.

read more

SOOJS Examples

We’ve made it. You are now fully ready to go forth with your new-found knowledge of SOOJS and build better and more maintainable JavaScript applications. The last few things I will leave you with are some samples of SOOJS in practice.

File Templates

Let’s start with file templates. There are 3 basic templates I advise. They are simple and make life 100% easier once you get them in your workflow. Even if you are only sparingly going to use SOOJS these really come in handy.

I will link to the GitHub repo here for the templates, as I hope to keep them fresh there:

GitHub: SOOJS Templates

TodoMVC

I took on the TodoMVC challenge with SOOJS as my only weapon to see how it would stack up against frameworks. It does amazingly well. I will embed to the todo application below, but also say that (again) the GitHub repo has the source code for this app.

 

read more

Basic MVC

You now have everything you need to implement SOOJS into any of your current or future projects. The organization of when to separate elements is the only real decision that remains.

MVC helps us here. I won’t go very deeply into this, but it’s simple to say that you will be best served if you try to very clearly separate the UI from the business logic and control of the system. And that sounds so simple. But a given rule like “show dates in local format” can give you fits to determine if it should be part of the logic of the controller or an implementation detail to the view. Those debates will continue forever.

For the time being let me emphasize a few components that are found in most every program.

• Controllers (logic)
• Controllers (view)
• Connectors
• Objects / Structures

This is not strictly a part of SOOJS, but is helps create the environment for a clearly defined SOOJS project.

I find it helpful to create controllers, and view controllers. They are really the same object, but I can clearly understand their rolls when I see a directory of “view controllers”. I know they are the UI implementation. Also, I know that if I’m in a controller or connector, or even an object and I’m trying to update the UI I know it’s the wrong place. It is likely the easiest place to have a bit of code in the “Item” class to update the checkmark when its own isComplete boolean is changed. But this is not about the easiest path. That is exactly how poorly constructed, expensive to maintain, ridden with bug applications are born. You have to be diligent about this yourself.

In the TodoMVC example project the files layout looks like the following:

 

From that image you can see the common layout I use for smaller projects. Of note is the ItemCollection (an array, essentially) that is in the controllers directory.

As you can see from the requests object these are the many things this collection does over and above what a standard array does.

Note: I very commonly code and organize so that my source can be collapsed in a meaningful way. It’s another benefit of having internal objects separating the parts.

The last item I will mention here is that of Connectors. Connectors are slices of code that call off-system in any way. They encapsulate the interactions cleanly and can very easily be tested when separated. It’s also very easy to use a different connector, or dummy up (stub) interactions when the connector itself is stand-alone. And finally, as one of the more delicate parts of an application you want to be able to lock changes to connectors whenever possible to prevent accidental changes to API implementations.

And when I say off-system, I really mean anything that is not core to the code you are writing. It could be a web service, or another piece of JavaScript written by another team that you simply implement. Very commonly they deal with data-in or data-out.

read more

The Delegate Pattern

You’ve reached the final element of the base pattern here. We’ve seen files and objects, internals and publics, readability and no training. Now the final step is to make sure these objects can easily communicate with the world, and have a reasonable standard to also listen to the world.

I will not go heavily into the delegate pattern here, you will find much more lucid explanations on the web. A quick explanation would be assigning an object to “listen” to another. That other object has “hooks” or delegateCallbacks defined so you know what to listen for. But this is all so theory driven. Let’s do code. How about starting with our dog from the previous example and adding a delegateCallback section:

Okay, with this I will pull out what we’re interested in and re-describe it here:

This object stands as a protocol definition in our class. I usually leave it at the very top so new developers can see very quickly what the object is capable of notifying the delegate of. You will also see a bit of boilerplate here testing delegate to make sure it handles this callback. This way the object doesn’t have to concern itself with if the delegate is fully formed, it only has to concern itself with itself.

Note: You can, of course, add required delegate callback handling mechanics into these classes at any time. SOOJS leaves the door open for any additional elements you think are needed. It is, after all, all your code.

Coupled with this delegate caller is the callbackHandlers object:

This is the place a SOOJS class handles callbacks and the object you pass as your delegateRef to other objects. To show this I need to construct a different example:

The JS Bin example

The above is an entire example of several objects talking to one another. The JS Bin example also shows how simple the UI implementation becomes when we’re dealing with discrete objects:

Then the delegate callback handlers handle updating the UI in any way needed.

This delegate pattern is amazingly strong. It also asks developers to create tightly managed systems. If there is an issue with something not happening when the final apple falls, you know where to look. Either that is not being announced to the delegate, or the delegate is not handling it. No more hunting around for any and everyone who may be observing the tree changes.

And this brings us to the final discussion of the SOOJS pattern. Even though everything you now know is the pattern, it’s hard to figure the best way to define objects in a customer-facing application. That’s where some basic MVC principles come in.

read more

Our first SOOJS Object

We are finally there! You have learned enough about all the JavaScript concepts that make SOOJS what it is. It’s time to dive into the real pattern itself. This should be much easier now that you see why things are being done this way.

Note: There is a LOT of JavaScript closure going on with SOOJS to manage scope. Closure is much less magical than it sounds. I will leave it to the reader to investigate on their own if needed.

So, now where is our object?

As a note, but you know this already, the above class would be in a file called Dog.js. Very likely in a subdirectory holding our standard objects.

So, let’s start here. This is the main mechanism of SOOJS. We start by overtly defining my as this in the very beginning. Thus we never bump into nasty scoping issues as we dive deeper into internal objects later. Now, everywhere within this class when we use my we mean this instance of the main object. I also show the delegateRef here because the delegate pattern is very emebeded in the SOOJS pattern. You can remove it or not use it (like anything else here) but I bet once you see the value it will become a great friend of yours, as it is mine.

Also, note that the signature here can be anything at all. I’ve added the breed and name from before just to show we could start with anything we like. This is, in essence, your constructor. Let’s step into the next elements:

 

Okay, it got just a little more complex here. First know that SOOJS advises an explicit “initialize” function to be called at the end of the class definition. There are some reasons I won’t cover here, but it has to do with forward-definitions. If you don’t wait until things are truly defined in the class then you run into all those odd “undefined” errors. Basically, you will call a function at the end to run the initialize() code. Very little else has any order of precedence in the pattern.

It would be fine to not include the init mechanism, and in simple objects I often find myself pulling the code out all together to make cleaner implementations, but the pattern has it there by default. Again, you are writing all of this so do whatever is needed. Later I will share some standard “templates” with you. If the editor you use allows for file templates I highly advise plugging these in. Then you will always start with a stubbed-out SOOJS class that has this stuff in this order already.

Great, let’s dive just a bit deeper. (See how easy this is now?)

 

Alright. Now we have something quite new here. And it’s a core concept in the SOOJS pattern. Internal objects to create namespace.

Scope is very important in an OO pattern. We need to be careful about not redefining things or attaching things at the wrong layer. SOOJS deals with all of these complexities with a little inner-object name-spacing. In this case I’m showing the requests object. It will be easiest if you don’t think of these things as objects as much as containers for functionality and scope. They are, of course, objects.

As you can see in the initialize() function we can now ask this dog to bark. So this is all coming together nicely. First, let’s extend our internal objects a bit to show why they are separated like this…

Okay, this is really filling in with a structure now. Looking closely at it you can see there is a new internal object defined: internals. This is exactly the same as the requests object we created earlier. Nothing magical here, and any names at all can be used.

Note: I highly advise sticking with these names for your early work. It’s this consistency that makes SOOJS a real pattern. If the next guy can’t trust that you have a requests object then all is lost.

The idea I’m showing you here (slowly) is that internal to the object there are sections or areas of scope. The internals object above is your object’s guts. This is where you can put all your functional work that you need to make the dog a Dog. It also serves (as the name indicates) as a private section. None of this will be visible to the outside user. Their code inspector will show them the requests object and requests.bark().

SOOJS is very concerned with code-completion and IDEs. One of the biggest reducers of bugs is clearly exposed APIs to objects and subsystems. If you have barkToConsole() exposed to the outside world as well as bark() then how does a developer using your object know which he should use? Are they the same? Are they equal? Then when someone needs to update the Dog object they have to account for the fact that some code-lines are pointing to bark() and others to barkToConsole().

Let’s illustrate this with a boolean that changes how our dog barks:

Okay, things are getting really large here. We have several namespaces (internal objects) that are being tested and called internally to keep things nice and tidy. Now the dog can bark in several ways depending on the debug setting. And this setting is specific to each dog.

If you’re reading along in the code and trying to make real sense of it I think things are starting to click about now. Basically, we have a fully-formed object. But wait… there is one thing that doesn’t work at all here. From the outside world let’s say we did this:

Then we pulled up our code completion dialog in an IDE for sallyDog and we don’t see anything externally exposed. We have forgotten to “hang” the requests object out for the public. That is very easy code, and standard in the SOOJS pattern. It looks like this:

And it’s placed right before the initialize() call. So we get this

After we do that what we see is this:

• sallyDog
  • requests
    • bark
    • getName

So, we have created a complete and encapsulated object here. There is one major item left to discuss and I’ll save that for the next section: the delegate pattern.

Oh, and if you are wondering about our object at this point it looks like this:

 

 

read more