Journey of Code Over the web: Plugin-Repository-Package-Usage

Recently I created a jQuery plugin jQWaffle, which you can find at Github.

Github

journey1

Here is an journey and the nitty gritty details that happened over the entire phase of the code development from code creation to version control and releasing the different versions. Once the versions were ready then packaging them and hosting them and making them available to everyone over the web.

It all begins with creating a layout with different menus for different use cases. I idea was to have a plugin so jQuery was the default choice as there were going to be multiple DOM manipulations.

Once the code was ready opting for Github is the defacto choice for open source projects. You can create a project and host the code in a Github repository. You can work on multiple features at the same time on different branches and merge them once completed in the master branch. You can also follow the pattern of having seperate production and staging branches.

Git

I used Git for version control. I commited my changes and pushed them to github. It is a command line tool to perform these operations. You can also use the GUI tool Github Desktop available on windows or the lesser known GitKraken avaiable across all operating systems.

Versioning

Once the plugin code completion part is done, we must add versioning. Initially 1.0.0 at first major release.

Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes
  • MINOR version when you add functionality in a backwards-compatible manner
  • PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

You can read more about the semantic versioning tags at https://semver.org/

To create a first release with the release no on Github visit the release section on your Github section. Click on Draft Release button to create first release.
github-release1

ECMA6

The plugin i was using few feature from latest javascript specification included in ECMA6. You can have a good overview and comparison of new features at http://es6-features.org

All the browser vendors do not support the latest specification features.

BABEL

Babel comes to the rescue. Add `.babelrc.json` file to root of the project. Install development dependencies npm install --save-dev babel-cli babel-preset-env

You can find a step by step guide at Babel Installation. I followed the Babel CLI Installation.

Once a release is done you can find a mention of Versioning Tags on github.

release tag

The first version of plugin i ready and it is time to make it available out in the world, adding it to a package manager.

Bower

I register the package on Bower. Bower keeps track of all these packages and making sure they are up to date. You can find a detailed list of steps to follow to create a package on Bower. It is pretty simple and straight forward.

Install Bower:- npm install -g bower

Add bower.json at root of the directory.

Register the package in bower
E.G.
bower register jqwaffle https://github.com/niteshp27/jQWaffle.git

Expect a similar output:-
bower jqwaffle#* resolve https://github.com/niteshp27/jQWaffle.git#*
bower jqwaffle#* download https://github.com/niteshp27/jQWaffle/archive/1.0.6.tar.gz
bower jqwaffle#* extract archive.tar.gz
bower jqwaffle#* resolved https://github.com/niteshp27/jQWaffle.git#1.0.6
? Registering a package will make it installable via the registry (https://registry.bower.io), continue? Yes
bower jqwaffle register https://github.com/niteshp27/jQWaffle.git

Package jqwaffle registered successfully!
All valid semver tags on https://github.com/niteshp27/jQWaffle.git will be available as versions.
To publish a new version, just release a valid semver tag.

Run bower info jqwaffle to list the available versions.

It install the Github repository as a bower package. Similarly you can unregister the bower package. Type the Github credentials to perform the operation. The package is over the web available for any one to use.

Usage

To use the bower package you can follow the below steps and we can get going.
bower install jqwaffle

There we go using the created plugin in another project.

Advertisements

Deploy Website to Azure

I wanted to explore the Azure cloud service of Microsoft and deploy a static React website I completed, on Microsoft Azure. Below are the step that you can follow on the updated Azure admin console panel to deploy an Hello World Html Site which is hosted on Github.

Here is the Hello World Html Site for site hosted on Github. You can visit Microsoft Azure Website and sign up to use the Azure free products for web-mobile – App service to host the website. Once create the URL will look something like this https://azurehelloportal.azurewebsites.net/

Azure free products for web-mobile

Visit the portal to create a new website. You can use get started and select the Web App – Quick start tutorial or directly on Web + Mobile to create Web App.

azure-portal

Fill up the name for the App choose the subscription if you purchased or signed up using any free monthly Azure credit. Microsoft does drop an email sometimes to promote use Azure, keep and eye on your Office365 email address. Select the Resource group. In short a resource group is a container for your resources, You can read about it in more details here. You can use and already created resource group or create a new one.

create site

Click on create. Your site will be created.

Visit the Resource Group tab in left menu to have a look at available resource groups.

 resource-group

IT’s time to visit our website where we will deploy our code which is hosted on Github using Git. The App Service section located on the left menu of the Dashboard screen.

dashboard-left-menu

Visit the Deployment Credentials section under the Deployment Menu to key in and set up the local git and FTP environment.

deployment-credentials

Next up Visit Deployment Option Menu to choose the deployment source to be git and select local git repository. Choose the performance test to test user load and duration.

deployment-option1

deployment-option2

deployment-option3

deployment-option4

Next visit the Properties Section below to copy the azure git url where we will be pushing out local git repository. We will need this later on. This will look something like this- https://niteshpatare@example.scm.azurewebsites.net:443/example.git

git-properties

Note down the git URL.

Visit the overview section where you can see all the git and ftp details as well.

site-overview

Back to the local machine. Open up your cmd prompt and run the following steps one after the another to deploy site to the azure. I consider you are not a newbie to git and have basic understanding of git commands.

git clone https://github.com/Azure-Samples/html-docs-hello-world.git
cd html-docs-hello-world
You can make any Changes as per your needs or else continue with fresh deployment.
git add –-all
git status
git commit -m "added files"

You will need the git URL from the azure portal that we copied earlier.
git remote add azure https://niteshpatare@example.scm.azurewebsites.net:443/example.git
git push azure master
Enter the credentials to complete the process.

Note:- Some time or another you are bound to run into the following error when everything goes well.

Error-You do not have permission to view this directory or page.

You have to set the starting Default document for your site. Visit Application Settings. Under Default Documents add the starting file name. E.G. start.html

final-application-settings

Below are different starting default documents.

default-documents

And we are good to go. Visit the deployed site. You can find the url in Overview section. It will be something like https://example.azurewebsites.net.

SCSS – Key Missed Parts

SASS (Syntactically awesome stylesheet) or SCSS (Sassy CSS) as we call it, are CSS preprocessors. Preprocessors generate css files and have their own syntax and own language.
E.g. SASS, LESS. SASS or SCSS is an extention of vanilla CSS that adds variables, mixins, nested rules and many other features.
Our SASS code gets compiled to properly formatted CSS, easing the issues of organising and maintaining code.
SCSS syntax is the most widely used by developers and designers. It makes writing CSS fun again.
SCSS is a superset of CSS written in same way but with new SASS features. SCSS makes writing maintainable CSS easier. The code is more redable in less time and with less code.
In SCSS the files are saved as “.SCSS”.

 

Variable:- 

A value can be set to a variable which is the used instead of the original value. They are time savers declare once and use it where required. E.g. $almond:#eee;
The default value is used only if value isn’t set or assigned any place else.
E.g.:- $default-text: $black !default;

 

Mixins:-

They are resuable piece of code. The purpose of mixin is to make a set of properties reusable. Mixins are functions and functions can accept parameters.
E.g.- @mixin overlay {
background-color:#eee;
}
.modal_bg {
@include overlay();
}

E.g.with parameters- @mixin border-radius($radius) {
$border-radius: $radius;
}
.box {
@include border-radius(3px);
}

 

‘&’ Ampersand parent selector:-

The ‘&’ Ampersand parent selector when we nest, it doesn’t add space between parent selector and child selector hence ‘&’ to join classes. Mostly used with pseudo selectors.
“&’ is a shortcut for parent selector.
E.g. .parent {
&:hover { text-decoration:none;}
}
Output:-
.parent:hover { text-decoration:none;}

 

@extend:-

@extend allows to inherit CSS from another source. CSS is maintainable as we add selector one by one in related selector. HTML remains semantic as each element keeps its descriptive class name.
E.g.- .message {
border: 1px solid #ccc;
padding: 10px;
color: #333;
background-color: transparent;
}

.success {
@extend .message;
border-color: green;
}

Output:-
.message, .success {
border: 1px solid #ccc;
padding: 10px;
color: #333;
background-color: transparent;
}

.success { border-color: green; }

 

Difference between Mixin and Extend:-

@extend doesn’t have parameters but mixin do.
@extend combines selectors but mixins don’t.
SASS @extend is more efficient as it writes common properties only once.

 

Placeholders:-

If we don’t want or need the any selector, then we can transform it into a Sass placeholder by replacing the dot with a percentage sign %.
E.g.- %message {
border: 1px solid #ccc;
padding: 10px;
color: #333;
background-color: transparent;
}

.success {
@extend .message;
border-color: green;
}
Output:-
.success {
border: 1px solid #ccc;
padding: 10px;
color: #333;
background-color: transparent;
}

.success { border-color: green; }

 

Comments:-

// single line comment.
/* multipleline comment */ :- Might not display at exact position
/*! Loud comment */ :- Will be displayed at exact location

 

Working with LESS and SCSS in Visual Studio 2015

I am demonstration a simple example to start working with LESS and SCSS in visual studio 2015.

First Set up web compiler

scr1

scr2

Click download and install.

Create an empty solution and add a project.

scr3

scr4

Add css folder and add a main.less file. Right click on the LESS file and compile it for first time.

scr5

scr6

It creates a compilerconfig.json where we can mention what are input and output file paths.

scr7

It automatically generates a css file and minified file with same name.

scr8

We can then include it in our html page and start adding css to the LESS file.

We also have the option to recompile the file or remove it from compilation altogether.

scr9

For scss files we follow the same steps.

Going further I added another less file and imported it in our main file and it works absolutely fine. It also generates sourcemap file in the converted scss to css file inline.

You can find the source code at the following github repo. https://github.com/niteshp27/setup-less-and-scss-in-visualstudio

Working with LESS in ATOM

ATOM is a open source text editor. Atom helps you write code faster with a smart, flexible autocomplete.  You can visit https://atom.io/, download and install it. We are going to work with LESS in ATOM IDE.

Once installed we can begin with installing the less package. For that we need to visit File -> Settings and then the Install tab.

scr1

Type less-autocompile and search for the package. The result will be something like below, click on install to install the package.

scr2

Create a LESS file named main.less and add the below parameters on first line of the LESS file main.less preceded by a //

out (string): This is the path where the CSS file is to be created
sourcemap (bool): This creates a create sourcemap file. I will give more details about sourcemap later in the blog. It is a boolean value true or false.
compress (bool): This will provide us an auto compress CSS minified file. It is a boolean value true or false.

scr3

We usually have different modules of css represented inside separate less file. In our example we find variable.less file. In the variable.less file add the below parmeter on first line of LESS file preceded by a //

main (string): This is the path to our main LESS file to be compiled.

scr4

The same applied for responsive.less file as well.

scr5

The LESS file auto compiles the LESS file on save.

Sourcemaps:-

Source maps seek to bridge the gap between higher-level languages like CoffeeScript and Sass and the lower-level languages they compile down to (JavaScript and CSS). Source maps allow you to see the original source (the CoffeeScript or Sass) instead of the compiled JavaScript or CSS while debugging.

A comment is added to the end of the generated CSS file:
/*# sourceMappingURL=screen.css.map */
This points to an additional file that was created during compilation: screen.css.map, which – as the name implies – is what maps all of the compiled CSS back to the source Sass declarations

To enable it in chrome follow the below screen

scr6

scr7

Configure criteria of content search webpart

The first step is to open site in sharepoint designer. Create a page layout and add a webpart zone first. It will look like this as given below:-

<WebPartPages:WebPartZone id=”g_F65E9C0D6A9E4BE49A9112742242B0E0″ runat=”server” title=”Right Row”><ZoneTemplate>

</ZoneTemplate></WebPartPages:WebPartZone>

Add content search webpart inside zone template via teh top menubar in sharepoint designer.

Apply the page layout to a newly created publishing page. Edit the page, configure the webpart that comes automatically as it is added in page layout. Configure search criteria settings:-

criteria-1

Save the page. Apply the webpart click ok. Page goes back to edit mode, click on export.

criteria-2

Open the exported file in the xml you will find the “DataProviderJSON” property. Copy that value which is a json.

criteria-3

Open html escape online utility:- http://www.freeformatter.com/html-escape.html#ad-output and escape this JSON value.

criteria-4

Replace the DataProviderJSON value in page layout with this escaped html. It will look something like below.
<WebControls:ContentBySearchWebPart runat=”server” AlwaysRenderOnServer=”False” ResultType=”” DataProviderJSON=”Escaped JSON” ……..>

</WebControls:ContentBySearchWebPart>

Save the page layout. Next time you create a new page with the above page layout, the page will have a pre-configured content search webpart.

Configure properties of content search webpart

We will be following the export method for configuring properties of content search webpart.

Open the website in a browser, edit the page which contains webpart zones, next click on add a webpart.

Add content search webpart via webpart, edit the web part select the correct options, select display template -> control and set the correct option then inspect the select box and check the value of selected option, it will be a url, copy that url.step1-export

 

Repeat same process for display template attribute “Item”. Add content search webpart via webpart, edit the web part select the correct options, select display template -> item and set the correct option then inspect the select box and check the value of selected option, it will be a url, copy that url.step2-export

 

Next apply that webpart edit option and then export that webpart.

step2-1-export

Open that webpart and search for that url in xml code you will find like this below:

step3-export

Now you found the attribute name of attributes of Display Templates control and item which are “RenderTemplateId” and “ItemTemplateId”.

Next you can go to Sharepoint Designer create a new page layout, add webpart zones and inside webpart zones zone template add Content Search Webpart and add the following values to the code. You can see the image below for the code.

E.g.
RenderTemplateId=”~sitecollection/_catalogs/masterpage/Display Templates/Content Web Parts/Control_ListWithPaging.js”
ItemTemplateId=”~sitecollection/_catalogs/masterpage/Display Templates/Content Web Parts/Item_TwoLines.js”

  1. To add vlaue for Control- Go to the page layout and add the url as attribute value of the attribute “RenderTemplateId”step4-exportstep4-1-export
  2. To add value for Item – Go to the page layout and add the url as attribute value of the attribute “ItemTemplateId”
    ItemTemplateId=”~sitecollection/_catalogs/masterpage/Display Templates/Content Web Parts/Item_TwoLines.js”step5-exportstep5-1-export

Save the page layout. Next when you create a page in browser and apple the newly created page layout you will get the already pre-configured Content Search Webpart.