A new technological direction for FreedomSponsors.

Hi everyone, quick post:

In the last 3 posts ([1], [2], [3], [4]), I talked about how you can use AngularJS to build a web application.

Starting now, FreedomSponsors architecture will be moving in that direction: a mobile first, MaterialDesign-based, SPA.

My intention is for FreedomSponsors to have a really friendly development environment that more people can work on, while also serving as an example of a high quality architecture for a web app. That way, I can help other web developers, and also get more help from the community to build FS because it will be a lot easier to contribute to the project, I hope.

If you would like to contribute, please subscribe to our mailing list [5] and introduce yourself, let us know a little about your current skills and how you want to help and what you would like to learn.
Right now, the most relevant skills are: responsive web design and front-end (css) development.

We’ll be managing our work using this Waffle board [6] + Github issues [7].

Hope to hear from you :-)

Tony Lâmpada

[1] – FS front-end project setup (1/3)
[2] – FS front-end project setup (2/3)
[3] – FS front-end project setup (3/3)
[4] – fsstatic2 (the new FS front-end on Github)
[5] – Subscribe to FS contributors mailing list
[6] – Waffle board (project status: look for status >= “Ready”)
[7] – Issues on Github (all issues go here, back and front-end)

An awesome setup for your AngularJS project (3/3)

This is post #3 of 3 to explain about fsstatic2. Beware: it may change forever how you approach web development. :-)

Let’s finish this.

docs.html – A component catalog AND a playground environment.

When working with AngularJS, it’s very useful to have a “playground area” where you can create components without necessarily changing the behaviour of the main application. The DOCS environment serves this purpose. It’s a collection of “test pages” which are able to showcase its own code. It’s very easy to add a new test page, let me show you:

This environment actually can serve multiple purposes:

Playground area: using this environment on their local machines, developers on your team can develop and test components individually. It’s very advisable that every component have its own test page.

Component documentation catalog: If you publish this application on the internet, people can check it out whenever they need to see which components are available, and how to use them.

Prototype showcase: Developers can show their work in progress to designers, clients, and stakeholders in general, in order to collect feedback and refine the direction the product is supposed to go.

So, this is another good practice:

Good practice #7: Have a component catalog.

Tests: running, debugging and coverage reports

Tests should go in the docs folders and be called “test_*.js”. Now there are a few things you want to be able to do with them, like:

  • Run them all [runtests --singleRun=true]
  • Watch for changes, and keep running [runtests]
  • Run a single test [runtests --grep=blabla]
  • Debugging [runtests, open localhost:9876/debug.html]
  • Generate test coverage report (sorry, forgot about this in the video) [runtests --coverage=true]

The video below shows you how

 

test_todo.js: how to write good tests

If you follow Good practice #5 you’ll end up with a codebase where most of your code will be inside AngularJS services. Well, this is *very* good for testing – among all the types of objects you can create with Angular, services are the easiest to test.

Take a look at our test (test_todo.js). I could have made that test use TODOModel directly, but instead I created another service TODOTester. When testing viewmodels like TODOModel, I found out that using a “tester service” like that allows me to write more expressive tests. I mean look at this code:

TodoTester.assert_count_todos(0);
TodoTester.type_and_add('one todo');
TodoTester.type_and_add('to twodos');
TodoTester.type_and_add('tdee throdos');
TodoTester.assert_count_todos(3);
TodoTester.remove(1);
TodoTester.assert_count_todos(2);
TodoTester.assert_todo_text(1, 'tdee throdos');

It really looks like we’re simulating a user ”driving” the application. You can even write the test first, give empty implementations to TodoTester methods – your tests will pass, then add the method bodies later. This gives you an incredible “TDD feeling” when you’re doing it.

Another detail worth mentioning is that the tests include api_mock.js, not api.js. This means you can reuse the same mock implementations you already have in your tests (and this is much much better than mocking ajax calls with $httpBackend). For example, we do that in TodoTester.type_and_add(). We know TODOModel.add() will make a (fake) ajax call, and all we need to do is to force our fake backend to respond by calling $timeout.flush().

expect(count).equal(TODOModel.todos.length); 
//still waiting for the "server" to respond
$timeout.flush(); //yay, the server responded!
expect(count + 1).equal(TODOModel.todos.length);

See?

Here’s another tip that may help you with your tests. You could create additional methods on the fake FSApi service (say, FSApi._set_todos(array)), which are only supposed to be used inside tests or DOCS sample pages, which would allow you to preload data on the “fake database”. Speaking more generally, you can add methods to your fake apis that change your fake backend’s behaviour. You can use those methods to load different scenarios both inside unit tests and test pages.

We talked a lot about tests and the good practice here is not so obvious this time:

Good practice #8: ViewModel tests should be talking in a user’s vocabulary.

You should think “I’m gonna write a test for requirement/scenario X” much more often than “I’m gonna write a test for method X”. High test coverage should be only a consequence of that approach. Most of the time this means having to create a “tester” service with method names that are very close to user actions. Sometimes you may also feel the need to create other types of test-helping services, like a “ScenarioLoader”. In any case, the code inside the test itself, should be “easy” enough for even non-programmers to understand.

Wrapping up

What we’ve seen here is more than a project’s setup. I believe that the techniques and ideas presented here can be applied to any web application project to improve architecture/code quality, maintainability, testability, development speed, and as a consequence, happinnes, for you and your team :-)

Perhaps this is a lot to remember, and if so, the list of good practices below will help, hopefully.

  • #1: Have a project help on the command line (help your team and your future self)
  • #2: Everything is a component (which uses other components)
  • #3: Have a mock API (with promises created out of $timeout)
  • #4: Plan for some flexibility in your templateURLs (with some global variable as a prefix)
  • #5: NEVER use the $scope as a view model. Put your models into services (this is very important!)
  • #6: Let me see the API first (helps answer the “What does this do?” question faster)
  • #7: Have a component catalog
  • #8: ViewModel tests should be talking in a user’s vocabulary (and you’ll need to create extra services for this)

OK, that’s all I had to say folks. Hope it helps.

Cheers! :-)

An awesome setup for your AngularJS project (2/3)

Posted originally on dicasdolampada.com.br

This is post #2 of 3 to explain about fsstatic2. Beware: it may change forever how you approach web development. :-)

So, let us continue.

index.html – How the main application works

Routing

There’s not much to say here, it just applies basic ui-router configuration to make a Single Page Application.

  • fs_main.js is responsible for setting up the routing rules
  • Each route has a template that is as simple as <fsissue></fsissue>
  • The toolbar has some <a ui-sref=”statename”> links on it that activate different routes

More details in the video below

Now, notice that even if we had chosen not to build an SPA, we could still use a similiar structure. For example, instead of having an SPA in the index.html file, we could have more pages, like home.htmlissue.html, and so on. The code on such a page, say: home.html, could look like:

<body ng-app="fs_main" layout="column" ng-controller="FSMainCtrl">
  <md-toolbar layout="row">
    <fstoolbar></fstoolbar>
  </md-toolbar>
  <div layout="row" flex>
    <div layout="column" flex id="content">
      <md-content layout="column" flex>
        <fshome></fshome>
      </md-content>
    </div>
  </div>
</body>

Can you smell another good practice here? Right…

Good practice #2: Everything is a component.

Our application should be structured as a composition of components, not very different from each other in terms of architecture. In our case I’ve decided that each component is a restrict=”E” directive. The result is a very standardized way of doing things. People on your team will be able to understand each other’s code faster because everything has more or less the same structure.

Mock api

Don’t talk to URL’s directly. Instead, hide your backend URLs behind a stateless Angular service with a bunch of methods that return promises.

Then, make an alternative implementation that pretends to talk to the backend, but actually generate hard-coded data in javascript and resolves promises with $timeout. This takes us to the next good practice:

Good practice #3: Have a mock API.

This will allow you to have an environment where you can switch between a full stack environment and front-end-only environment. This ability will most likely boost the speed on your development process.

Authentication

Does it even make sense talking about authentication if we don’t have a real backend yet? The answer is YES. The front-end plays a big part in the authentication process and we can go and implement the client part beforehand, just like we can do it with anything else, really. We don’t even need a video this time (but you will have to take a look at the code as you keep reading!)

FSAuth’s (fsauth.js) responsibility is to provide information about the current user to the rest of the application. Whoever needs to know if we are authenticated can just call FSAuth.authenticated(). If they need the current username, then FSAuth.user.username. The <fslogin> directive (fslogin.js/fslogin.html) has a viewmodel (FSLoginModel) that is activated in the login screen. When the user fills the login form and hits OK, FSLoginModel.login() will ask our ”backend” to authenticate us - FSApi.login(username, password) - and then give FSAuth the currently logged user by invoking FSAuth.set_user().

Now there’s an important detail here. We want the real backend implementation of FSApi.login(u, p) not only to return a json with information about the current user. This particular response also needs to come with a set-cookie header that will tell the browser to store a session variable in a cookie, which will be sent in all subsequent requests. That way, the backend can know who is the user making those requests. This is what is supposed to happen when we call FSApi.whoami() - if the request comes from an authenticated user, this should return that user data, otherwise the response must say something like “Oh, you’re just nobody :-)”.

Now FSAuth, during its initialization (see _check_for_authentication) will call FSApi.whoami() and store the current user in itself if it is authenticated. The current mocked implementation of FSApi.whoami() will always return an authenticated user – this is arbitrary. So if the user refreshes the page, FSAuth will still know who the current user is.

Our main <fstoolbar> (fstoolbar.js/fstoolbar.html) is also dependent on FSAuth. You can notice that the toolbar’s right side will show different content depending on the result of FSAuth.authenticated().

The logout feature is left as an exercise for you to understand alone :-)

So, the only piece missing in our authentication process is the backend. If we have correct, real implementations for FSApi.login(u, p) and FSApi.whoami(), it should work for real.

Template URLs

Anywhere we include a template we have a path prefix before the template URL. For example, the templateURL for the <fslogin> directive is FS.BASE_URL+’login/fslogin.html’.

This will give you more flexibility to move included .js files relative to the main html file. Let me show you.

And don’t forget this also goes for templates included with ng-include.

This is important, so let’s add it as another good practice to our list:

Good practice #4: Plan for some flexibility in your templateURLs.

This can help you have with the dev vs. prod build differences, and it will also save you some trouble when you have to move stuff around.

todo.js – A detailed example of how to make a component

The DOCS page has a <todo> component that illustrates how to make a simple component. This doesn’t relate to any feature in FS, it’s just that I didn’t have a better idea for a sample component.

The main recommendation that I give to everyone using angular is this: do not use the $scope as a model. It’s better to put the model implementation inside a service. Let me show you.

Of course, this is another good practice.

Good practice #5: NEVER use the $scope as a view model. Put your models into services.

I can’t stress enough how important this is. Having your view models inside services allows you to have a much cleaner code as a result of a clear separation of concerns. As a bonus, it also makes your code very easy to right unit tests for.

Your screen needs some AJAX action? No problem, inject an API service into its viewmodel and let the model handle the AJAX for you. Need a loading-please-wait animation? Sure, have a boolean attribute in your model that tells the template when to display it. But keep your distance from the $scope object. Trust me, the less you rely on it, the better off you are.

If you look at the rest of the directives in the src/ folder you can see that I intend to apply this same pattern to all components.

Some other detail that you might have noticed is the way that the code inside the TODOModel is laid out:

var m = {
    newtodo: '',
    adding: false,
    todos: [],
};

angular.extend(m, {
    add: add,
    remove: remove,
});

There’s actually another good practice behind this:

Good practice #6: Let me see the API first.

You can see what TODOModel is supposed… er… to do (:P) after a quick glance on just the snippet above, right? It’s a plain object with those 3 attributes that make up its state, and those two operations that change it. Seeing the attributes and operations at the top allows me to realize faster what are this object’s responsibilities.

All right, this is enough for post #2. In the next and last post we’ll cover.

  • docs.html – A component catalog AND a playground environment.
  • Tests: running and debugging
  • test_todo.js: how to write good tests

One last thing: please repeat with me one last time (out loud is better):

I will never use the $scope as a viewmodel. 

Good.

Just to be sure :-)

An awesome setup for your AngularJS project (1/3)

Published originally in dicasdolampada.com.br

This is post #1 of 3 to explain about fsstatic2. Beware: it may change forever how you approach web development. :-)

In the past two years I’ve been working a lot with web development and AngularJS.
FreedomSponsors is an open source web application that I made before that, so it doesn’t have in it all those cool new things that I have learned.

I’d like to change that, so I’m rebuilding FreedomSponsors as a AngularJS-based Single Page Application.
The primary reason I’m doing it is because I believe that if FS has a really friendly development environment, more people will be able to collaborate with it and this will help the project move forward.

There’s also a secondary reason: I want this new website to serve as example for people who want to learn more about good practices for web development – this is what this post is about.

The resulting webapp right now is still far from complete (feature-wise), but its architecure already has some good ideas that you may want to apply on your project. Or, if you’re starting a new project, you can just clone the project and go from there.

The main architectural features it has right now:

  • fshelp - A list of commands easy at hand so we don’t need to memorize anything
  • JsHint: Everyone loves their javascript style checked
  • DOCS (docs.html): A “playground” page that can be used both for 1) developing/testing new components, and 2) documenting how to use them
  • The app (index.html): A single page application that you can run locally (ui-router based)
  • Mock API: With this we can mock all of the backend JSON api. Focus on front-end development first; worry about the real backend api later.
  • Fast save/refresh cicle: Using devbuild/runserver, you end up with a development environment where you can save files and hit refresh, with no build steps in between (except for scss files, at least for now)
  • Javascript tests, with coverage report – Bonus: you can reuse the same mock api in the tests too
  • Production build: Build in production mode with all js and html concatenated in a single file. Bonus: it also works with file:// so it should be possible to port it to mobile with no (or maybe very little) modifications using Cordova (yes I intend to do this with FS in the future)
  • Generated CSS using Sass

Exciting, isn’t it? :-)

So, let’s dive into it with a little more detail…

Get it up and running

It should be really simple and fast, just follow the readme on github, or watch the video below.

Oh, can you please let me know in the comments below how long it took you? :-)

Now there’s a good practice worth noting here:
Good Practice #1: Have a project help like this.

fshelp

People working in your project should not have to waste their time memorizing commands (if the predefined commands have autocomplete, even better)
When you have someone new in your team, this should save you some time

Folder structure: What is where, and how the build works.

Here’s a quick summary for you

src/                            # All your code is belong to me<br />src/pages/index.html            # The main application<br />src/pages/docs.html             # The DOCS application<br />src/**/*.{js|html|scss}         # The bits and pieces of the app<br />src/api/api.js                  # The real API that will talk to the backend<br />src/api/api_mock.js             # The fake API which is what we'll be using for a while<br />src/**/docs/**/*.{js|html}      # Documentation pages and unit tests (none of this will see production)<br />src/**/docs/**/test_*.js        # Unit tests<br />docs_src/                       # The docs framework<br />lib/**/*.{js|css}               # Third-party stuff<br />settings/*.js                   # Some settings that differentiate dev vs. prod environments<br />dist/                           # The result of our build goes here<br />dist/index.html                 # src/pages/index.html, after some find/replaces<br />dist/docs.html                  # Guess!<br />dist/css/fs.css                 # src/**/*.scss gets compile here<br />dist/css/lib{.min}.css          # Part of lib/**/*.css gets concatenated here<br />dist/css/lib{.min}.js           # Part of lib/**/*.js gets concatenated here<br />dist/js/fs.js {P}               # src/**/*.1 gets concatenated here (except for **/docs/**)<br />dist/js/fsdocs.js {P}           # src/**/docs/**/*.js gets concatenated here<br />dist/js/docs.js {P}             # docs_src/**/*.1 gets concatenated here<br />dist/js/fs.js                   # Part of lib/**/*.js gets concatenated here<br />testlib/**/*                    # Libraries used only in unit tests<br />gulpfile.js                     # THE build<br />fsdev.sh                        # Handy commands

(Items marked with {P} are only relevant in the production build)

The video below will demonstrate a little more what the build can do.

There’s something I forgot to show in the video, which is, when you build the app using prodmock, it also works with file:// like this:

fsstatic2_file_protocol

A good side effect of this is that in the future we are more likely to be able to make an IOS/Android app out of it using Cordova (yes I intend to to that in the future).

OK, this concludes the first post. In the next two posts I’ll talk about:

  • index.html - How the main application works
  • todo.js - A detailed exampled of how to make a component
  • docs.html – A component catalog AND a playground environment.
  • Tests: running and debugging
  • test_todo.js: how to write good tests

Stay tuned.

Welcome, LibreJS users!

librejs

GNU LibreJS is a browser plugin that aims to address the JavaScript problem described in Richard Stallman’s article The JavaScript Trap. Basically, what is to block the execution of any javascript files that aren’t explicitly licensed as free software.

A while ago, Richard Stallman contacted me and asked me if I could try and make FreedomSponsors compatible with LibreJS. At the time I was really busy and couldn’t do it. But recently I made another attempt and succeeded (yay!)

Making your website compatible with LibreJS is hard-ish, with more hidden obstacles than I anticipated (and I’ll bug them more about this soon at librejs mail list!). But in the end, there were a few hidden advantages too:

  • Concatenating all my js and template files made pages load faster
  • Using the right content-type for json responses is always a good thing
  • Forcing yourself to know exactly what third party libs and licenses you’re using is a good thing too.

So if you use LibreJS, your browser will probably stop complaining about freedomsponsors.org now. And if it doesn’t, please let us know.

In case you’re a webdeveloper creating a website, please consider making it compatible with LibreJS. In that case, check out this other post with a few tips to make LibreJS like your website.

Cheers!

Tony Lâmpada

Bitcoin payments are working again

Earlier today I sent an email to all users telling you that Bitcoin payments were temporarily suspended due to a problem on http://blockchain.info API service.

A few hours ago the issue has been resolved on blockchain’s side and we’ve enabled Bitcoin payments again, so all is good.

Also, on that email I made a few mistakes that I’d like to correct here.
The last thing I want is to be the guy spreading innacurate information.

Mistake #1

> [1] – http://www.computerworld.com/s/article/9238118/Mt._Gox_under_largest_DDoS_attack_as_bitcoin_price_surges

I sent the URL above meaning to point to a recent news article, but that is actually an old news from April 2013 (duh!)

The correct link would be:
[1] – http://www.coindesk.com/mt-gox-halts-bitcoin-withdrawals-price-drop/

Mistake #2

> During the last couple of days the Bitcoin network has been under heavy DDoS attacks.
> Those attacks forced MtGox (and some other Bitcoin exchange services) to halt bitcoin transactions temporarily while they are working together with core developers to solve the issue.

This is not accurate. The problems with BTC withdrawal delays on MtGox are not caused by DDoS attacks on the Bitcoin network but by a technical issue in the network known as “transaction malleability”.

The following press releases from MtGox help clarify the issue
https://www.mtgox.com/press_release_20140207.html
https://www.mtgox.com/press_release_20140210.html

Mistake #3

> Blockchain.info did not halt transactions but they made some changes to their API behaviour in a preventive effort to avoid being affected by those attacks.

Wrong again, that was a fast assumption I made. According to their blog, they had a problem with one of their database nodes, and turned on DDoS protection to not make the problem worse.
http://blog.blockchain.info/2014/02/12/having-trouble-using-our-services/

That’s a lot of mistakes on a single email isn’t it?
Shame on me, sorry about that! That’s what I get for writing and sending emails in a hurry.

Thank you all for your support and understanding.
Special thanks to rprnospam for reaching out and pointing out those mistakes.

Tony Lâmpada

New feature – Project Pages

project_page

Last week we rolled out a new feature that people has been asking for for a while: Project pages.
Now, Projects on FreedomSponsors have a page (example above) displaying:

  • Logo, description, and a link to its official home page
  • Some project-wide statistics
  • Top sponsors and developers
  • Project’s issues
  • An activity feed on that project

Tagging

Users can add tags to projects. Tags are fetched using the StackOverflow API, so you can only choose among tags that are valid on StackOverflow (which should be enough for FS). In the future, issues will be searchable by those tags as well.

Watching

Users can also toggle a watch on a project to be notified about its activities. When you’re watching a project you get email notifications when:

  • Someone edits those project details or tags
  • Someone sponsors an issue on that project
  • An offer is changed or revoked or paid
  • A new issue is proposed
  • A developer starts working or abort work or resolve on an issue.

To get notified about issue comments as well, you need to watch issues inidividually.
If you are watching both an issue and a related project, you only get notified once for updates on that issue.
Also you never get email updates for actions you do yourself.

We hope this update will help overall experience on FreedomSponsors

A big thanks to our sponsors!

This new feature was actually sponsored on FreedomSponsors, and it just happened to be the issue with the biggest offer so far.

The sponsors:

BTC 2.00 + USD 60.00 is roughly equivalent to US$ 2000.00 (using today’s Bitcoin rate) – which was split evenly between developers TonyLampada and Rafael Augusto dos Santos.

Than you guys, you’re awesome!
We’ll keep making FreedomSponsors better and better.

FreedomSponsors on Linux Format

DSC06362

Linux Format is a magazine in the U.K. about Linux and Free Software.
On their Christmas issue (#178) they did a nice piece on Crowdfunding,
and they talk a fair deal about FreedomSponsors! Good thing they deliver worldwide, and we could get our copy sent here to Brazil ^^.

DSC06365

They also interviewed Campadrenalin, who brilliantly explained the
motivations behind issue sponsoring.

DSC06367

Thanks Campadrenalin, that was very nice!
And thanks Linux Format, that was a great article.
And thanks to everyone out there who keeps helping make FreedomSponsors grow.
Let’s rock even more on 2014 ;-)

Happy holidays and a happy new year!

- Tony Lâmpada

– UPDATE: TechRadar.com has uploaded the full article on their site. Check it out: http://www.techradar.com/news/internet/the-power-of-crowdfunding-how-to-make-the-most-of-it-1206834

Check out FreedomSponsors new and improved design!

home

We’re very excited to announce our improved design. We rebuilt the layout base and redesigned the home page and the issue page from scratch, focusing on delivering a better and more engaging user experience.

We want to make a special mention to Rafael Santos, the front-end master mind behind it. Thank you Rafael!

We hope you like the new look as much as we did, so please send us your feedback and let us know if you bump into any issues.
You can drop a comment on our feedback section, file an issue on Github, or even make a pull request!

And we are just getting started, there are many new improvements to come. Stay tuned.

Continue to FreedomSponsors

- Tony Lâmpada
FreedomSponsors – CEO

Brasília, here we go! / Brasília, aí vamos nós!

pythonbrasil

This post is in portuguese :-)

Começa amanhã o maior evento da comunidade brasileira de Python – o Python Brasil!
Este ano, a conferência acontecerá em Brasília, e vai rolar em paralelo com a Plone Conference.

O evento vai contar com a presença de nomes fortes da comunidade, como Luciano Ramalho, Fernando Masanori, Henrique Bastos, Renzo Nuccitelli e muitos outros.

O FreedomSponsors também estará representado pelo nosso CEO, Tony Lâmpada, que vai apresentar “FreedomSponsors – Python, Crowdfunding e Software Livre” (slides disponíveis) na trilha de empreendedorismo. Bacana demais! :-)

Confira a grade do evento e siga o perfil do evento no twitter!

Um abraço e até lá!

© 2015 FreedomSponsors

Theme by Anders NorenUp ↑

Follow

Get every new post on this blog delivered to your Inbox.

Join other followers: