Baasic AngularJS blog Starter Kit - part 1

As announced in our earlier posts, we have recently opened Baasic to a wider audience, so now is the right time to explain how to unleash its potential with your web applications and sites. We will use AngularJS in this tutorial, as it is one of the most popular client side JavaScript frameworks at the moment. This does not mean that you have to be an AngularJS guru to use Baasic: the level of detail should be enough for designers and developers that don’t have too much experience with this stack.

I do assume that you have a basic knowledge of Git and development tools like node.js, Bower and Gulp. If you have any problems with the understanding of concepts described in this article, we are here to help.

Each solution built on top of Baasic has at least two different parts: - a server-side Baasic application, which can be opened and maintained through Baasic backend administration, and holds the data for your solution. Depending on your preferences and business requirements, this part can be fully transparent for you as a developer. Contrary to traditional data stores, it allows you to store fully dynamic data in it, and it provides ready-to-use, higher-level data structures and business logic. Therefore, you can immediately use articles, comments, tags, and - very soon - social login, networking, discussion boards, and similar functionality, without writing any custom code. - your front-end code, written in server-side (PHP, ASP.NET, Java, …), client-side (javascript with all its frameworks) or native (iOS, Android) languages and frameworks. The beauty of Baasic comes in a form of standard pieces of functionality - modules and templates - that can be used without custom programming. Think of login and other membership modules, article editors, navigation, blogs, discussion boards and other similar social networking modules. All of these modules, templates and starter kits are and will continue to be open-sourced, so if you need to customize their functionality, it is easy to do so.

There is a thorough description on how Baasic backend and dashboard work, so please make sure to read it if you are just starting your work with it. In addition to that, you might want to learn about our AngularJS SDK and Baasic REST API if you intend to customize the functionality of the starter kit.

Opening a new application

You should start by registering for an account at Baasic home page. We are currently in the beta testing phase, but support all the functionality described in this article. Once registered, you should open a new application. Baasic applications are fully independent server-based containers that allow you to store different types of data for your mobile, web or desktop apps, including key-values, value sets, articles, tags, comments, and fully dynamic resources. They come together with a fully featured back-end administration and include user and role management functionality.

Opening a new application is easy; just log in to your Baasic account and click on the “Add a new application” button.

Proceed with entering your application name and unique identifier (api key), along with your user info. Note that each application opened under a single Baasic account can have a different username and password.

That’s it! Your new application is opened and ready. Please remember your application identifier, though, you will need to use it with our code samples.

Working with the starter kit

As a client-side prerequisite, you should install the basic tools for your operating system: Node.js, Bower and Gulp. Start by cloning the AngularJS blog starter kit repository. After that, go into the root folder of the started kit you just cloned and type

npm install

npm (Node Package Manager) will go through its configuration file (package.json) and install all dependencies. It may take a couple of minutes to download and install everything; when it is finished, just type

gulp serve

and you are almost ready to go.

Here is what you will see at this point.

In its default state, this kit points to the main demo site and pulls its content from it. As it would not be a nice thing to have thousands of users editing it, you will need to point your kit to the application you opened at the beginning. It is easy - just go to the \src\app\app.js and enter your Baasic application unique identifier (api key) here:

baasicAppProvider.create('<api-key>', {
        apiRootUrl: 'api.baasic.com',
        apiVersion: 'beta'
    }); 

As your new application is empty, there is no content in it, and the demo page will be blank after this switch. However, you can now log in and start entering your own content.

Functionality

This starter kit provides a bare-bones blog engine. Initially, it shows a list of blog posts, with search, tags, and login modules contained within a panel on the right side. To keep things simple, it allows you to add/edit/delete blog posts using the markdown syntax and add tags to posts. We deliberately removed more advanced features so the basic functionality is not obscured by them: however, future samples will include a complete content management functionality.

This kit is based on the Baasic article data type. Articles provide a standard way to gather written work for the purpose of publishing various documents, news, posts and other similar items. Each article has a set of properties that can be edited interactively to change their appearance and behavior. We can distinguish following article types: - Published article - a publicly available article, - Article pending publication - an article that is waiting on publication until the predetermined Publication date, - Draft article - an unfinished article saved to the Baasic data storage and - Archived article - an older article separated in the archived data storage for potential future use.

All articles can be previewed and edited via Baasic back-end administration.

Going back to the project you’ve just set up: here is the basic structure of the starter kit.

Let me explain a few basic concepts; in the next article, I will provide more details about AngularJS code and how it extends the basic article data structure to allow it to host blog posts.

Folder structure

There are only a couple of folders in this solution:

• .tmp is an output folder used by Gulp (see below) for CSS compilation, template caching, and similar tasks.
• bower_components is where Bower - javascript package manager - holds the utility javascript packages that we need.
• node_modules is where Node.Js holds its modules. In our scenario, it is mostly used by Gulp, but not exclusively.

You do not need to modify the content of these folders, as they are automatically created and maintained by Gulp, Bower and Node, according to their configuration files. The real fun starts with the src folder. Its subfolder app contains the code for all components used in this starter kit. themes subfolder controls the UI of the solution, and holds assets (images and third-party javascript), CSS files and module templates. We have strived for a total separation of UI and code aspects, so you don’t need to deal with the code files at all if you only need to change the look and feel of the application.

Tools

This starter kit is using Gulp to automate build tasks. Gulp is a javascript task runner and streaming build system similar to the other popular tool, Grunt. Unlike Grunt, it is using Node.js streams, so file manipulation is all done in memory, and a file isn’t written until you tell it to do so. Gulp saves us a ton of time during development, as it automates all repeating tasks, including minifying JavaScript and CSS files, unit testing, linting files to check for errors, compiling CSS preprocessor files, and much more. It prefers code over configuration, and the majority of its magic is controlled via gulpfile.js in the root of the kit.

In line with this philosophy, you don’t need to manually edit the main index.html in the app root. There is an index method that takes care of adding references to all third-party Bower components, as well as your application scripts and CSS files. Here is a code snippet from gulpfile:

function index() {
    var opt = { read: false };
    return gulp.src('./src/app/index.html')
        .pipe(g.inject(gulp.src(bowerFiles(), opt), { addRootSlash: true, ignorePath: 'bower_components', starttag: '<!-- inject:vendor:{{ext}} -->' }))
        .pipe(g.inject(es.merge(appFiles(), cssFiles(opt)), { addRootSlash: true, ignorePath: ['.tmp', 'src/app'] }))

Therefore, you will not want to manually edit content between * <!– inject:… –> * and * <!– endinject –> * comments, as it will be regenerated on each build. If you need to add a reference to your file manually, you can do it outside these regions.

Changing the UI

It is easy to change all visual aspects of Baasic modules. You will want to change the templates in the themes folder. These are standard AngularJS templates - HTML enriched by the various Angular directives and the markup used for data binding (the expressions in double curly braces {{ }}), meaning they are easy to use and modify even if you don’t have any previous experience with Angular. Note that we are using Pleeease, a Node.js CSS processor that helps create clean stylesheets, support older browsers and offers better maintainability. You can alternatively use plain old CSS, or any of the CSS preprocessors of your choice.

Conclusion

The takeaway of this post? Clone the AngularJS blog starter kit - npm install - change the appliction unique identifier (api key) in the app.js - and you are ready to start customizing its look and feel to suit your needs. Gulp and all other tools are here just to make your everyday work easier. Next time we will talk a bit about the functionality contained within starter kit modules, and will learn how to use them in the real world, outside our example. In the meantime, stay tuned and let us know if have any comments or questions.