Fork me on GitHub
2sxc 9.43 for DNN 7 to 9
Website Builder, Content Manager, App-System: open-source and fun
You are here: Home  >  Learn  >  Simple AngularJS in DNN with 2sxc4ng

Simple AngularJS in DNN thanks to 2sxc4ng

Simple AngularJS in DNN thanks to 2sxc4ng

AngularJS is a very powerful JavaScript framework to develop Apps with. You can use it for

  1. Very simple Apps - like contact forms
  2. Multi-dialog Apps
  3. Data management Apps
  4. Galleries, image rotators etc.
  5. extremely complex things like ERPs and similar

Basically anything you can dream of in JavaScript can be done with AngularJS, and it's probably easier to do it in AngularJS than with any other JavaScript framework at the time. The information on this page are meant to help you get started with AngularJS. It's very easy from within 2sxc, because we added some helpers to automate all the difficult things for you. 

Discover how easy AngularJS is with best practices

This is a recorded session from DNN Connect 2015 where I showed how to use AngularJS within DNN. It includes a lot of best practices which make it much easier to get started with AngularJS. Highly recommended both for newbies as well as people who have experience with Angular or DNN - because in combination it has a few aspects which make it easy to go wrong. 

The slogan: If you're new to AngularJS or if you're still using $scope in your code, you have to watch this. 

Tutorial App - Feedback Form Best Practices

The App from the video which uses REST, AngularJS and many best practices. It has lots of commented code to ensure you will be able to create your own solutions based on this. 

Documentation AngularJS and 2sxc 7

The following pieces of information should help you get started. It will focus on using AngularJS within DNN, not specifically on learning AngularJS by itself. We'll cover the following topics:

  1. Scripts to include in your HTML to ensure that all components work automatically
  2. What you must do with your HTML template that the App starts automatically
  3. Some background so you understand what the auto-start will do with your App
  4. Documentation related to the 2sxc4ng system so you can use it within your App

Scripts to include in your page

Whenever you use AngularJS in your code you should add the following scripts to your page

  1. angularjs.min.js - contains AngularJS in minified code. If you use the copy in 2sxc you'll also benefit from un-minified debugging
  2. 2sxc.api.min.js - the 2sxc javascript controller - contains helper code which is very valuable for JSON services; it's required by 2sxc4ng
  3. 2sxc4ng.min.js - this starts your AngularJS application automatically and takes care of various important things

Normally you will also want to specifiy loading order etc., so this is the code you should use:

<script src="/DesktopModules/ToSIC_SexyContent/JS/2sxc.api.min.js" data-enableoptimizations="100"></script> 
<script src="/DesktopModules/ToSIC_SexyContent/Js/AngularJS/angular.min.js" data-enableoptimizations="101"></script> 
<script src="/DesktopModules/ToSIC_SexyContent/Js/AngularJS/2sxc4ng.min.js" data-enableoptimizations="110"></script> 
In addition you'll need your own code files etc.

Simple JS code snippet

// SyntaxHighlighter makes your code snippets beautiful without tiring your servers.
// now for DNN thanks to
var setArray = function(elems) {
    this.length = 0;
    push.apply(this, elems);
    return this;

Use sxc-app instead of ng-app to auto-load

In AngularJS there is a system called a bootstrapper, which loads all necessary components to ensure you app will work. This is a bit like compiling - just called bootstrapping in this case. Outside of DNN most demos will tell you to use ng-app="App-Name" etc. but in DNN we had to add more features. This has many reasons but the two most important ones are that

  1. In DNN we cannot assume that your AngularJS is the only app on a page (called a SPA = Single Page Application). Instead we must assume that multiple Apps can be on the same page - sometimes even multiple occurrences of the very same App.
  2. In your app you will often need to access services from the server - usually using $http, ngResource, content, query or similar. These all need to be preconfigured properly to ensure that security is maintained.

So there are 2 things you must do to ensure your AngularJS App is auto-loaded (bootsrapped):

  1. Use attribute sxc-app="your-app-name" - this is the marker that will auto-load the app
  2. Use one of many possible attributes to tell the bootstrapper the DNN ModuleId. Typicall this is done through id="App-[Module:ModuleId]" 

Understanding the automatic bootstrapping

The following is more technical - you can skip it for now. But once you've worked with AngularJS a bit you'll want to revisit this because it's important in advanced scenarios to understand how everything is wired up. In 2sxc/DNN the Auto-Bootstrapper will do the following for you

  1. Lookup the module-id to use in your app. 
    1. For this it will check the URL (because sometimes it says mid=42 or mid/42 in the URL which will take precedence over the html-attribute)
    2. Otherwise it will retrieve it from one of various attributes in your template. We recommend that you place the ID in the id attribute, mixed with some text (the text will be removed) like app-34 (do this like id="app-[Module:ModuleId]" in your HTML). If you really need your id to be different, use app-instanceid or data-instanceid instead. 
    3. It will then provide this value as a constant to your app under the name AppInstanceId - you will probably never need this, but it's there
  2. Create a constant called AppServiceFramework containing the DNN Services Framework - again you will probably never need this (see later) but it's there
  3. Create a constant called HttpHeaders containing all the headers which every AJAX / REST / WebAPI request needs - you won't need it, but it's there
  4. Add 2sxc4ng to the dependencies of your app
    1. this will do some further bootstrapping, mainly reconfiguring the $http (see next note)
    2. provide various services like
      1. sxc - which is the sxc javascript controller for this module - in most cases you won't access this
      2. content - a service which helps you get/write content to the 2sxc server through REST
      3. query which will help you call server side queries through REST
  5. Reconfigure $http (the basic AJAX-request service) 
    1. to automatically rewrite simple URLs to the correct 2sxc URLs (so $http.get('app-content/Feedback') is converted to the long DesktopModules/API/... path
    2. to automatically add all the necessary security headers for DNN
    3. to automatically show a nicer error if something goes wrong

Built-In Service: sxc

This service is used in the background by other services like content or query. It provides direct access to the 2sxc-controller for this module. 

If you don't understand that - don't worry. It's a background-system. Since everything is automated, you will usually not need to work with this service directly. Just know that it's there :)

Built-In Service: content

The content-service is a helper to access content. It helps you to do all CRUD operations:

  1. create content
  2. read / retrieve / get content - one or all items of a type
  3. update content
  4. delete content

They are basically wrappers for the $http just taking care of some extras. In V7 they are very simple, but further functionality will be added in the future. The result of a call is always a javascript promise. 

To learn more I recommend to try the demo-app linked above; it contains samples for all these operations. Here the summary

  • To give your module access to the service, just declare a dependency on 2sxc4ng - and your function signature will need to get the content object. If you don't understand this - check out the demo-app. 
  • If you only need a one-liner, just go content('Content-Type-Name').someaction(...). For example
    • content('Feedback').get(); // get one
    • content('Feedback').get(17); // get all. 
    • content('Feedback Category').get().then(function (result) {
           // more code which will be executed when all feedback categories come back
      } )
    • content('Feedback').create(newFeedbackObject);
    • content('Feedback').create(newFeedbackObject).then(function (result) { ... });
    • content('Feedback').update(id, updatedFeedbackObject);
    • content('Feedback').update(id, updatedFeedbackObject).then(function (result) { ... });
    • content('Feedback').delete(17); // delete #17
    • content('Feedback').delete(17).then(function (result) { ... }); 
  • if you want to do more complex things then you can keep a reference to the object, like
    • var feedb = content('Feedback');
      feedb.create(...).then(function (result) {
         feedb.get().then(function (allFeedbackResurt) {
           // code to update the list of feedback-items

Bulti-in Service: query

This is also a $http shortcut and helps you access content-queries from the server. Usage:

  • query('queryname').get()
  • query('queryname').get().then(function (result) { ... } );

To use this service, give your module a depenedncy on 2sxc4ng and tell the method to need query. If you don't understand this, check out the demo-app.

Remember that queries are Admin-only by default. To allow public access to queries (like for populating a drop-down in a contact-form) remember to modify security settings.