I've previously experimented with developing Alfresco clients using a number of different application frameworks. In this blog post I'm going to step through the process of creating a page using React and deploying it into Share.
Although I'm using React in this example I could have just as easily used Vue.js, Aurelia, Angular, Ember or any framework that provides a CLI or project template for developing and packaging a Single Page Application.
Create Your Page
You should now have an application running locally with a great development experience with hot-reloading, etc provided by create-react-app. If you make an REST API call to (using an URL starting with /share/proxy/alfresco) then you should get a basic authentication challenge and once you've provided some valid credentials you'll be able to access data from the Alfresco Repository (don't worry, when you deploy into Share the authentication will be handled for you by Share/Surf).
I've built a very simple client for browsing company home. You can view/copy the code from this GitHub repository (check out this tag for the code at the time of writing this post). The client contains 4 components:
...that provide a simple interface for browsing.
Build and Deploy
Once you're happy with your page then run:
npm run build
This will populate the build folder with the resources that you want to deploy into Share.
This is referenced from the page and creates a mapping to a template.
Copy the contents of the index.html file into the alfresco/templates/react.ftl file but replace all occurrences of "/static" with "/share/res".
If you change the contents of any JS or CSS and rebuild it will be necessary to copy and update the contents of index.html again because the resources are named with a checksum (just like Surf/Aikau does!)
Now bundle up the contents of the copied build folder (not including the build folder itself) as a JAR file and copy it into the WEB-INF/lib directory of Share and restart the server that it is running on.
Once the server has restarted you'll be able to login to Share and then you will be able to access your page at /share/page/react.
Include the Header and Footer
If you want your users to access this new page with the context of Share then it makes sense to include the standard header and footer.
Update the react.ftl file initially so that it looks like this:
<#include "/org/alfresco/include/alfresco-template.ftl" /> <@templateHeader> <!-- Insert CSS link here --> </@> <@templateBody> <divid="alf-hd"> <@regionscope="global"id="share-header"chromeless="true"/> </div> <divid="bd"> <!-- Insert contents of body element here --> </div> </@> <@templateFooter> <divid="alf-ft"> <@regionid="footer"scope="global"/> </div> </@>
...and then add the CSS <link> element and the contents of the <body> element from index.html into the commented sections.
Update your JAR file with the changes, redeploy and restart the server and when you access the same URL you'll see the header and footer.
Add a Link to the Header
Obviously it's not ideal for users to have to enter a URL into the browser to get to your new page so let's add a link into the header bar.
This Stack Overflow question and answer provides a good overview on doing this properly (go on, give it an up vote - you know you want to!) but the basic steps in this case are as follows:
Create an alfresco/site-data/extensions/react-extension.xml file containing:
Repack your JAR file, deploy it to /share/WEB-INF/lib and restart the server
Now on each page in Share you'll see a link to your new page:
It's very easy to take advantage of the development environments provided for modern web application frameworks and deploy the output into Share. Some of the techniques shown in this post may be old but are still extremely effective which shows the value in a properly architected framework.