Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found

Target

Select target project
  • documentation/doc
  • PhilH/doc
  • louis.csn/doc
  • fabien4vo/doc
  • rngadam/doc
  • anastasia/doc
6 results
Show changes
Hide whitespace changes
Inline Side-by-side
Showing
with 698 additions and 829 deletions
source/import_documentation/devops/migrate_gitlab.rst deleted 100644 → 0
View file @ 98e4b41e
Gitab migration process
=======================
For LDP package release
-----------------------
- Reference to the `configuration
doc <./setup_continous_delivery_for_python#configure-project-on-gitlab>`__
1. Create the new project on https://git.startinblox.com by importing
the existing one from https://git.happy-dev.fr
2. Check the points 2 to 5 of the configuration doc (this is normaly
imported with the project)
3. Apply the point 6 of the configuration doc (variables aren’t
imported)\*
4. Clone the new project or update your remote in your local copy (ex:
``git remote set-url origin git@git.startinblox.com:djangoldp-packages/djangoldp-project.git && git pull``)
5. Update the ``.gitlab-ci.yml`` according to the configuration doc
6. Archive the project on the old gitlab
Note: (*) values for variables can be found in the original project
source/import_documentation/devops/release_workflow.rst deleted 100644 → 0
View file @ 98e4b41e
Releases workflow
=================
- Public: SIB devs
Overview of the code release flow
---------------------------------
.. figure:: ../../_static/images/import_documentation/devops/docs/code_release_flows.png
:alt: code release flows
code release flows
Delivering applications
-----------------------
The applications delivery works with multiple levels of validation:
- Unit testing is automatically triggered for ``all`` branches
- Integration phase is manually triggered on ``feature/*`` branches
- Acceptance phase starts automattically when pushing/merging on
``master`` branch
- Live deployment is manually executed after acceptance on ``master``
branch
.. figure:: ../../_static/images/import_documentation/devops/docs/deployment_pipeline.png
:alt: deployment pipeline
deployment pipeline
Use the ``Pipelines`` menu to control deployment over test environments:
.. figure:: ../../_static/images/import_documentation/devops/docs/test_environments.png
:alt: Test environments
Test environments
And staging + production environments:
.. figure:: ../../_static/images/import_documentation/devops/docs/staging_environments.png
:alt: Staging environments
Staging environments
You can use the ``Environments`` section to track the versions deployed
across environments.
.. figure:: ../../_static/images/import_documentation/devops/docs/all_environments.png
:alt: Environments overview
Environments overview
Working with alpha branches
---------------------------
How to make a hotfix on stable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Propose a hotfix from ``master`` branch:
::
$ git checkout master
$ git checkout -b hotfix/something
# work work work
$ git commit
$ git push -u origin hotfix/something
Then make a proper ``merge request`` into ``master``.
How to make a new stable release from alpha
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``master`` branch only accepts ``fast forward`` merges. So it is
necessary to prepare the prerelease branch in order to make such merges:
::
$ git pull --all
$ git checkout alpha
$ git merge master
$ git push
Then make a proper ``merge request`` into ``master``.
How to set the next prerelease version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The next prelease version is decided by parsing the commit messages
(like normal release) on the next push. Once the prerelease level is set
it is kept until the next release.
Force a bump (according to the configured release rules):
::
$ git checkout beta
$ git commit --allow-empty -m 'minor: force minor bump for beta'
$ git push
If the first commit pushed doesn’t trigger the wanted bump. You still
can delete all prerelease published tags since last stable on gitlab and
the corresponding publication on NPM registry.
Then you can make a commit with the appropriate message and push again.
source/import_documentation/devops/setup_continous_delivery_for_node.rst deleted 100644 → 0
View file @ 98e4b41e
Setup Gitlab CI/CD for a Node package
=====================================
- Public: developers
- Reading: 5 minutes
Configure project on gitlab
---------------------------
This step requires ``maintainer`` profile on the project.
1. CHeck the ``autodeploy`` user has a ``maintainer`` profile on the
group or project (``Members``)
2. Protect the ``master`` branch allowing only ``maintainers`` to merge
and push (``Settings > Repository > Protected branches``)
3. Allow ``fast forward merge`` only
(``Settings > General > Merge Requests``)
4. Allow ``merge only if the pipeline succeeds``
(``Settings > General > Merge Requests``)
5. Configure ``pipeline strategy`` to ``clone``
(``Settings > CI/CD > Pipelines``)
6. Configure CI/CD variables for authentication
(``Settings > CI/CD > Environment variables``):
============= ============== ==========
Variable Value Protection
============= ============== ==========
``GL_TOKEN`` ``**********`` protected
``NPM_TOKEN`` ``**********`` protected
============= ============== ==========
\*****: Ask to devops for tokens.
Notes:
- The ``fast forward merges`` are mandatory for **prereleases**.
- The ``merge only if the pipeline succeeds`` only makes sense if there
is **unit testing**.
Configure project in code
-------------------------
Release management
~~~~~~~~~~~~~~~~~~
Configure the code packaging by adding a ``release`` section in
``package.json``:
::
$ vi package.json
{
"name": "<your package>",
"version": "0.0.0",
"repository": {
"type": "git",
"url": "https://git.startinblox.com/<path/to/package>.git"
},
"release": {
"branches": [
"master",
{"name": "alpha", "prerelease": true}
],
"plugins": [
["@semantic-release/commit-analyzer", {
"preset": "angular",
"releaseRules": [
{"type": "major", "release": "major"},
{"type": "minor", "release": "minor"},
{"type": "*", "release": "patch"}
]
}],
"@semantic-release/release-notes-generator",
"@semantic-release/gitlab",
"@semantic-release/npm"
]
}
}
Notes:
- Replace ``<your package>`` by the name of your package.
- The ``version`` will be automatically set at deployement step.
References:
- https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration
Pipeline execution
~~~~~~~~~~~~~~~~~~
Configure pipeline execution in repository:
::
---
image: node:11
stages:
- test
- release
test:
stage: test
script:
- echo 'Make your tests here !'
except:
- tags
tags:
- sib
publish:
stage: release
before_script:
- npm install -g semantic-release@v17 @semantic-release/gitlab
script:
- semantic-release
only:
- master
- alpha
tags:
- deploy
IMPORTANT: Don’t forget to replace the ``Make your tests here !`` with
the relevant tests for your project. Not testing your application
automatically completly defeat the concept of continuous delivery !
Push configuration
------------------
Send to remote:
::
$ git add .
$ git commit -m 'feature: configured releases'
$ git tag -a v0.1.0 -m 'initial version'
$ git push --follow-tag
Setup prerelease on existing branch
-----------------------------------
Create an ``alpha`` branch from existing ``dev`` branch:
::
$ git pull --all
$ git checkout dev
$ git checkout -b alpha
$ git merge master
$ git push -u origin alpha
source/import_documentation/devops/setup_continous_delivery_for_python.rst deleted 100644 → 0
View file @ 98e4b41e
Setup Gitlab CI/CD for a Pip distribution
=========================================
- Public: developers
- Reading: 5 minutes
Configure project on gitlab
---------------------------
This step requires ``maintainer`` profile on the project.
1. Check the ``autodeploy`` user has a ``maintainer`` profile on the
group or project (``Members``)
2. Protect the ``master`` branch allowing only ``maintainers`` to merge
and push (``Settings > Repository > Protected branches``)
3. Allow ``fast forward merge`` only
(``Settings > General > Merge Requests``)
4. Allow ``merge only if the pipeline succeeds``
(``Settings > General > Merge Requests``)
5. Configure ``pipeline strategy`` to ``clone``
(``Settings > CI/CD > Pipelines``)
6. Configure CI/CD variables for authentication
(``Settings > CI/CD > Environment variables``):
================= =============== ==========
Variable Value Protection
================= =============== ==========
``PYPI_USERNAME`` ``startinblox`` protected
``PYPI_PASSWORD`` ``**********`` protected
``GL_TOKEN`` ``**********`` protected
================= =============== ==========
\*****: Ask to devops for tokens.
Notes:
- Python projects doesn’t support **prereleases**.
- The ``merge only if the pipeline succeeds`` only makes sense if there
is **unit testing**.
Configure project in code
-------------------------
Release management
~~~~~~~~~~~~~~~~~~
Add ``__version__`` variable somewhere in ``__init__.py``:
::
__version__ = '0.0.0'
Create a file ``setup.cfg`` at the root of your project, alongside the
directory of your app. Configure code packaging by adding a
``semantic-release`` section:
::
[metadata]
name = <your package>
version = attr: <your package>.__version__
description = StartinBlox package
long_description = file: README.md
long_description_content_type = text/markdown
license = MIT
classifiers =
Programming Language :: Python :: 3
[options]
packages = find:
[semantic_release]
version_source = tag
version_variable = <your package>/__init__.py:__version__
commit_parser = commit_parser.parse
Create a file ``.gitlab-ci.yml`` at the root of the project, alongside
the previous one. Edit it to configure pipeline execution in repository:
::
---
image: python:3.6
stages:
- test
- release
# this stage only make sense if you have unit tests
test:
stage: test
script:
- echo 'Make your tests here !'
except:
- tags
tags:
- test
publish:
stage: release
before_script:
- pip install python-semantic-release~=5.0 sib-commit-parser~=0.3
- git config user.name "${GITLAB_USER_NAME}"
- git config user.email "${GITLAB_USER_EMAIL}"
- git remote set-url origin "https://gitlab-ci-token:${GL_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git"
- git fetch --tags
script:
- semantic-release publish
only:
- master
tags:
- deploy
Push configuration
------------------
Send to remote:
::
$ git add .
$ git commit -m 'feature: added gitlab CI'
$ git tag -a v0.1.0 -m 'initial version'
$ git push --follow-tag
source/import_documentation/devops/setup_continous_delivery_for_sib_application.rst deleted 100644 → 0
View file @ 98e4b41e
Deploy your SIB application
===========================
Requirements
------------
In order to run your application you have to configure your web serveur
to serve a static folder (let say ``www``). The configuration itself
depends on your hosting provider.
Set up SSH authentication on your server
----------------------------------------
Generate a keypair (or use an existing one):
::
$ ssh-keygen -t ecdsa -f gitlabci -N '' -C 'deploy@gitlab'
And copy the public key to your server:
::
$ ssh-copy-id -f -i gitlabci.pub <user>@<server>
Pipeline deployment with Gitlab CI
----------------------------------
Configure the ``APP_CONFIG`` variable in the Gitlab pipeline. It is a
JSON string of the configuration file you can generate with
``jq -c . config.json``.
In a ``.gitlab-ci.yml`` file:
::
image: node
stages:
- deploy
deploy_staging:
stage: deploy
environment: staging
script:
- echo "$APP_CONFIG" > config.json
- echo "$SSH_PRIVATE_KEY" | tr -d '\r' > gitlab.key && chmod 600 gitlab.key
- npm install
- npm run build
- scp -i gitlab.key -o StrictHostKeyChecking=no -r dist/* <user>@<host>:~/www/
only:
- staging
source/import_documentation/devops/sib_in_containers.rst deleted 100644 → 0
View file @ 98e4b41e
SIB in docker containers
========================
This is not intended to support production running.
Setup your SIB server
---------------------
1. Create your ``packages.yml`` according to the documentation.
2. Create the ``Dockerfile``:
::
FROM python:3.6
ENV PATH="/root/.local/bin:${PATH}"
RUN pip install --user -U sib-manager
WORKDIR /opt
RUN cd /opt/ && sib startproject sib_server
ADD packages.yml /opt/sib_server/packages.yml
RUN cd /opt/sib_server && sib install sib_server
EXPOSE 8000
CMD cd /opt/sib_server && python manage.py runserver 0.0.0.0:8000
3. Build the image:
::
# docker build -t sibserver .
4. Run the container:
::
# docker run --rm -p 127.0.0.1:8000:8000 -d sibserver
Serve your client app
---------------------
Launch a container from within your code folder:
::
# docker run --rm -v $PWD:/code -w /code -u $UID -it -p 127.0.0.1:3000:3000 node npm install && npm run watch
source/import_documentation/devops/tests/node_release_management.rst deleted 100644 → 0
View file @ 98e4b41e
Test version releases with node
===============================
Configure release management
----------------------------
Confiugre semantic release in project:
::
$ vi package.json
{
"name": "siblab",
"version": "0.1.0",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC",
"description": "",
"release": {
"branches": [
"master",
{"name": "alpha", "prerelease": true}
],
"plugins": [
"@semantic-release/commit-analyzer"
]
}
}
Setup with gitlab-CI:
::
$ vi gitlab-ci.yml
---
image: node
stages:
- test
- release
test:
stage: test
script:
- echo 'Make your tests here !'
except:
- master
- tags
publish:
stage: release
before_script:
- npm install -g semantic-release@v17 @semantic-release/gitlab
- git checkout $CI_COMMIT_REF_NAME
script:
- semantic-release
only:
- master
- alpha
Test the commit publication in docker
-------------------------------------
::
$ docker run -v $PWD:/code -w /code --name testnode -it node bash
# npm install -g semantic-release @semantic-release/gitlab
# export GL_URL='https://git.startinblox.com'
# export GL_TOKEN=<token>
# export NPM_TOKEN=<token>
# semantic-release --dry-run
Test the prerelease workflow
----------------------------
Patching on alpha
~~~~~~~~~~~~~~~~~
Make a first patch on alpha:
::
$ git commit -m 'init: initial commit'
$ git tag -a v0.1.0 -m v0.1.0
$ git checkout -b alpha
$ git commit --allow-empty -m 'feat: first commit on alpha1'
$ git push --all --follow-tags
Results for ``master`` pipeline:
::
ℹ Found git tag v0.1.0 associated with version 0.1.0 on branch master
ℹ Analyzing commit: fix: hotfix on master
ℹ The release type for the commit is patch
ℹ Analysis of 1 commits complete: patch release
ℹ The next release version is 0.1.1
✔ Created tag v0.1.1
Results for ``alpha`` pipeline:
::
ℹ Found git tag v0.1.0 associated with version 0.1.0 on branch alpha
ℹ Analyzing commit: feat: first commit on alpha1
ℹ The release type for the commit is minor
ℹ Analysis of 1 commits complete: minor release
ℹ The next release version is 0.2.0-alpha.1
✔ Created tag v0.2.0-alpha.1@alpha
Repository after pipelines executions:
::
$ git log --graph --oneline --all --decorate --date-order
* ae5d4a8 (HEAD -> master, tag: v0.1.1, origin/master) fix: hotfix on master
| * 19e6aa9 (tag: v0.2.0-alpha.1@alpha, origin/alpha, alpha) feat: first commit on alpha1
|/
* 19a5d24 (tag: v0.1.0) init: initial commit
Increment patching:
::
$ git checkout alpha
$ git commit --allow-empty -m 'fix: keep working on alpha'
Results for ``alpha`` pipeline:
::
ℹ Found git tag v0.2.0-alpha.1@alpha associated with version 0.2.0-alpha.1 on branch alpha
ℹ Analyzing commit: fix: keep working on alpha
ℹ The release type for the commit is patch
ℹ Analysis of 1 commits complete: patch release
ℹ The next release version is 0.2.0-alpha.2
✔ Created tag v0.2.0-alpha.2@alpha
Merging alpha in master
~~~~~~~~~~~~~~~~~~~~~~~
Merging ``alpha`` in ``master`` triggers the version bump by analyzing
the new commits from ``alpha`` branch. When pushing again in ``alpha``
branch the new tag ``v0.2.0`` is not in the ``alpha`` history, so it
keeps incrementing from previous release.
To make the version bump available on ``alpha`` there is 2
possibilities:
1. Allow only fast forward merge in ``master``:
::
$ git checkout master
$ git merge --ff-only alpha
fatal: Not possible to fast-forward, aborting.
$ git checkout alpha
$ git merge master
$ git checkout master
$ git merge --ff-only alpha
Updating 70f176b..8563ed1
Fast-forward
**merge** ``master`` on ``alpha`` **before** fast forwarding ``alpha``
in ``master``
2. Merge back in ``alpha``:
::
$ git checkout alpha
$ git merge --ff-only master
Updating 4e3f382..a9e1eed
Fast-forward
**merge back** ``master`` on ``alpha`` **after** merging ``alpha`` in
``master``
Repository after pipelines:
::
$ git log --graph --oneline --all --decorate --date-order
* 96abdd6 (HEAD -> master, tag: v0.3.2, origin/master) fix: hotfix in master
| * d78a2ae (tag: v0.3.2-alpha.1@alpha, origin/alpha, alpha) fix: another fix on alpha
|/
* 8563ed1 (tag: v0.3.1) fix: another fix on alpha <-- in both histories (fast forward)
* 70f176b fix: hotfix on master
| * 17e24c3 (tag: v0.3.1-alpha.1@alpha) fix: another commit on alpha after merging back from master
|/
* a9e1eed (tag: v0.3.0) merge: branch 'alpha' <-- in both histories (merged back)
|\
| * 4e3f382 (tag: v0.2.0-alpha.4@alpha) feat: minor bump in alpha
| * 3674bd4 (tag: v0.2.0-alpha.3@alpha) fix: another fix on alpha
* | 5d513b0 (tag: v0.2.0) merge: branch 'alpha' <-- only in master history
|\ \
| |/
| * 4350b55 (tag: v0.2.0-alpha.2@alpha) fix: keep working on alpha
* | ae5d4a8 (tag: v0.1.1) fix: hotfix on master
| * 19e6aa9 (tag: v0.2.0-alpha.1@alpha) feat: first commit on alpha1
|/
* 19a5d24 (tag: v0.1.0) init: initial commit
- How next ``alpha`` release is set ?
- How to merge ``alpha`` in ``master`` ?
source/import_documentation/djangoldp_guide/djangoldp-references.rst
View file @ 405339e9
......@@ -96,7 +96,7 @@ Some packages may require some configuration to work properly. It is a good prac
Here you have :
* `a list of all the package available <https://git.startinblox.com/djangoldp-packages/>`__
* `Explanation on how to make one <develop-sib-ldp-packages.html>`__
* `Explanation on how to make one <https://docs.startinblox.com/import_documentation/develop-sib-ldp-packages.html>`__
If the description of the available packages is unclear, open an issue to ask for more description.
......@@ -106,27 +106,33 @@ The Server section
This section contains all parameters to the server itself. All this section is loaded as a Django configuration object to initialize the server.
see https://docs.djangoproject.com/fr/2.2/topics/settings/
see https://docs.djangoproject.com/fr/2.2/topics/settings/ for a detail explanation of all settings
The extra config module
-----------------------
The server parameters can be changed at different levels. They are overriden in the following order:
The DjangoLDP server also load a `settings.py` module when it exists in along with the `settings.yml`.
1. The DjangoLDP core default settings
2. :ref:`The DjangoLDP package settings`
3. The code from :ref:`the extra settings module`
4. The `server` section of the YAML settings file
The DjangoLDP packages capabilities
===================================
Which means a value written in the server section of `settings.yml` will override any parameters given by the core or the djangoldp packages.
Among other things, the package has a special file allowing a package to load settings when the djangoldp server starts. The `djangoldp_settings.py` file can reference custom variables and load extra middlewares (they are added to the ones loaded by the djangoldp server itself).
The `MIDDLEWARE` and `INSTALLED_APPS` parameters make exception to that behavior. Those lists are extended from previous values instead of being rewritten. When duplicated entries are detected in those settings, only the first items present in the list are kept.
The extra settings module
-------------------------
The `settings.yml` server section doesn't support dynamical configuration. When this is required, python code for configuration can also be loaded from a `settings.py` module along with the `settings.yml`.
The DjangoLDP package settings
==============================
The DjangoLDP packages support settings declaration through a special `djangoldp_settings.py` at the module's root. This file is fetched by the djangoldp core at runtime and all parameters are loaded following the settings resolution order. (see :ref:`The server section`)
.. code-block:: python
# cat mypkg/mypkg/djangoldp_settings.py
MIDDLEWARE = []
INSTALLED_APPS = []
MYPACKAGE_VAR = 'MY_DEFAULT_VAR'
As any other packages, local packages needs to be referenced in the project `settings.yml`:
.. code-block:: yml
ldppackages:
- mypkg
source/import_documentation/djangoldp_guide/install-djangoldp-server.rst
View file @ 405339e9
.. _djangoldp-guide-intro:
Get started with the DjangoLDP server
#####################################
What is behind the DjangoLDP server ?
=====================================
Startin'Blox is a front framework, based on a server named `DjangoLDP <https://git.startinblox.com/djangoldp-packages/djangoldp/>`__ and based on `Django <https://www.djangoproject.com/>`__.The DjangoLDP server is adapted to be compatible with Linked Datas convention.
Startin'Blox is a front framework, based on a server named `DjangoLDP <https://git.startinblox.com/djangoldp-packages/djangoldp/>`__ and based on `Django <https://www.djangoproject.com/>`__.The DjangoLDP server is adapted to be compatible with Linked Data's convention.
As a reminder and as specified in :ref:`Startin'Blox presentation <sib-presentation>`, Startin'Blox is data source agnostic,
i.e. it adapts to data sources that are compatible with the Linked Data Platform conventions.
......@@ -21,16 +23,33 @@ Requirements
The DjangoLDP server requires:
* python 3.6
* python 3.11
* pip and virtualenv installed
* postgresql database (for production)
* sqlite3 (for development)
* Django 4.2
.. note::
If you're working on many project in Python, we advice you to use `a virtual environement <https://virtualenvwrapper.readthedocs.io/en/latest/>`__.
If you're working on many project in Python, we advice you to use `a virtual environment <https://docs.python.org/3/library/venv.html>`__.
.. note::
`See the documentation to set it with Docker <https://docs.startinblox.com/import_documentation/install-sib-server.html#initiate-the-server-with-docker/>`__.
From a fresh environment, get the last version of DjangoLDP:
Optional: Set your virtual environment
=======================================
If you want to set a virtual environment, you can do it with the following commands:
.. code-block:: bash
cd /path/to/your/project
python -m venv myenv
source myenv/bin/activate
Install DjangoLDP
=================
From the virtual environment, get the last version of DjangoLDP:
.. code-block:: bash
......@@ -52,7 +71,7 @@ Add a package to your `settings.yml` file, let's start with `djangoldp_account`:
.. code-block:: yml
dependencies
dependencies:
- djangoldp-account
ldppackages:
......
source/import_documentation/djangoldp_guide/server-architecture.rst
View file @ 405339e9
......@@ -33,7 +33,7 @@ You'll find the right package in the documentation of each component.
A request in detail
===================
.. figure:: ../_static/images/servers-of-the-future.png
.. figure:: ../../_static/images/servers-of-the-future.png
:alt: How we imagine the servers of the future
......
source/import_documentation/first_step/Solid-introduction.rst
View file @ 405339e9
Our SOLID introduction
======================
`SOLID <https://solid.mit.edu/>`__, for SOcial LInked Data, is a project started in 2015 and led
in the 3WC by `Tim Berners Lee <https://fr.wikipedia.org/wiki/Tim_Berners-Lee>`__, the inventor of
in the W3C by `Tim Berners Lee <https://en.wikipedia.org/wiki/Tim_Berners-Lee>`__, the inventor of
the web who aims to rethink the way we build application in order to give back the power back to the final user.
For us SOLID project is above all a philosophy, a goal to reach and that inspires us.
......@@ -18,7 +18,9 @@ It is a set of standards on which we agree internationally to enable our applica
.. warning::
This page should be improved. `Any feedbacks is welcome <https://mailto:alice@startinblox.com>`__
This page should be improved. `Any feedback is welcome`__.
.. _Any feedback is welcome: alice@startinblox.com
Our API
-------
......@@ -93,7 +95,7 @@ Did you notice the presence of a context ?
]
}
It is a way to go from the Json to `JsonLD <https://fr.wikipedia.org/wiki/JSON-LD>`__
It is a way to go from the Json to `JsonLD <https://fr.wikipedia.org/wiki/JSON-LD>`__.
That’s mean that we encode `Linked
Data <https://en.wikipedia.org/wiki/Linked_data>`__ using JSON.
......
source/import_documentation/first_step/faq.rst
View file @ 405339e9
......@@ -20,7 +20,7 @@ If you want to add/change something on this documentation, `here are the instruc
* **What is Solid?**
We're working to make some popularizations for differents audiences. In the meanwhile, `have a look on the official presentation <solid.mit.edu//>`__.
We're working to make some popularizations for differents audiences. In the meanwhile, `have a look on the official presentation <https://solid.mit.edu//>`__.
* **This is open source?**
......@@ -29,11 +29,11 @@ The whole project is under `MIT licence <https://git.startinblox.com/framework/s
* **Why the documentation is not in markdown?**
This documentation in is `Restructured Text <https://docutils.sourceforge.io/rst.html>`__. `Have a look to this article <https://www.ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/>`__ if you want to understand our choice.
This documentation in is `Restructured Text <https://docutils.sourceforge.io/rst.html>`__. Have a look to `this article <https://www.ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/>`__ if you want to understand our choice.
* **You cannot find the question you have?**
`Send your question <https://mailto:alice@startinblox.com>`__ to the the maintainer of the doc or
`Send your question`__ to the maintainer of the doc or
`open an issue on the doc <https://git.startinblox.com/documentation/doc/-/boards/>`__.
.. _Send your question: alice@startinblox.com
\ No newline at end of file
source/import_documentation/first_step/get-started.rst
View file @ 405339e9
.. _podcast-tutorial:
Getting Started : Startin'blox Podcast Tutorial
***********************************************
......@@ -5,7 +7,7 @@ Presentation and Objectives
===========================
Startin'blox provides SOLID components called "blox" to build-up a website or a webapp that can consume and
manage data from various SOLID-compatible sources (to learn more `about Startin’blox components <about-our-components>`__). This tutorial shows the various front-end blox available
manage data from various SOLID-compatible sources (to learn more :ref:`about Startin’blox components <about-our-components>`). This tutorial shows the various front-end blox available
in the framework and describe step-by-step how to use it to make a podcast reader and sharing application.
This application is build as a blox itself and can be embeded in a website by just dropping a
``<solid-podcast>`` tag in the page.
......@@ -47,7 +49,7 @@ Setup the environment and display data
To use the Startin'blox framework, just embed it in the head of your html :
.. code-block:: html
.. code:: html
<!DOCTYPE html>
<html>
......@@ -74,7 +76,7 @@ We can now use our first blox : ``<solid-display>``. Startin'blox use the `HTML
which is part of the webcomponents standard, to create those blox. So you can use it as any other HTML tag,
like ``<video>`` or ``<select>``. This blox simply displays the data provided by the linked data source :
.. code-block:: html
.. code:: html
<solid-display data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml" no-render/>
......@@ -92,7 +94,7 @@ Organize and format data
To put data in order, we use the ``fields`` tag :
.. code-block:: html
.. code:: html
<solid-display
data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
......@@ -104,7 +106,7 @@ To put data in order, we use the ``fields`` tag :
We can also use a **widget** to specify how each field must be shown :
.. code-block:: html
.. code:: html
<solid-display
data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
......@@ -123,6 +125,7 @@ It starts to look better !
Any HTML element can be used as widget, but Startin'blox also provide **built-in widgets** to easily manage specific
cases. To display images from their url, use the ``solid-display-img`` widget :
.. code-block:: html
<solid-display
......@@ -138,14 +141,15 @@ nested. The word before the opening bracket is the group name and can be used to
.. code-block:: html
<solid-display
data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
fields="title, image.url, meta(itunes:author, itunes:category.text), description"
widget-title="h1"
widget-image.url="solid-display-img"
widget-meta="p"
no-render
/>
<solid-display
data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
fields="title, image.url, meta(itunes:author, itunes:category.text), description"
widget-title="h1"
widget-image.url="solid-display-img"
widget-meta="p"
no-render
/>
.. figure:: ../../_static/images/import_documentation/podcast_tutorial/Render3-Podcast-Tutorial.png
:alt: Data displayed with image
......@@ -156,7 +160,7 @@ Apply CSS to have your own look-and-feel
``solid-display`` uses standard HTML to display the data, and that HTML can be styled with CSS.
.. code-block:: html
.. code:: html
<style>
solid-display {
......@@ -178,7 +182,7 @@ Apply CSS to have your own look-and-feel
You can also target specific field with an attribute selector because ``<solid-display>`` component adds a
``name="[field]"`` attribute to the displayed data.
.. code-block:: html
.. code:: css
[name="itunes:category.text"]{
display: inline-block;
......@@ -194,6 +198,7 @@ You can also target specific field with an attribute selector because ``<solid-d
But sometimes it's easier and cleaner to use classes. ``class-[field]`` tags let's you specify a class name.
.. code-block:: html
<style>
......@@ -216,15 +221,17 @@ But sometimes it's easier and cleaner to use classes. ``class-[field]`` tags let
no-render
/>
You can also use arbitrary text (enclosed by single quotes) in the fields list to display a text node :
.. code-block:: html
.. code:: html
<solid-display
data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
fields="title, image.url, meta('By: ', itunes:author, itunes:category.text), description"
[...]
/>
<solid-display
data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
fields="title, image.url, meta('By: ', itunes:author, itunes:category.text), description"
[...]
/>
.. figure:: ../../_static/images/import_documentation/podcast_tutorial/Render6-Podcast-Tutorial.png
:alt: Data displayed, CSS and text enclosed by sigle quotes
......@@ -239,20 +246,22 @@ a list we have to tell the framework that it should be treated as multiple value
This is achieved with the ``multiple-[field]`` attributes. This tag creates a nested ``<solid-display>`` for each entry in
``item``. ``multiple-[field]-fields`` attribute is used to control which nested fields are displayed for each item.
.. code-block:: html
<solid-display
data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
fields="title, header(image.url, info( meta('By: ', itunes:author, itunes:category.text), description)), item"
widget-title="h1"
widget-image.url="solid-display-img"
widget-meta="p"
class-itunes:category.text="bordered"
widget-header="header"
multiple-item
multiple-item-fields="title"
no-render
/>
<solid-display
data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
fields="title, header(image.url, info( meta('By: ', itunes:author, itunes:category.text), description)), item"
widget-title="h1"
widget-image.url="solid-display-img"
widget-meta="p"
class-itunes:category.text="bordered"
widget-header="header"
multiple-item
multiple-item-fields="title"
no-render
/>
.. figure:: ../../_static/images/import_documentation/podcast_tutorial/Render7-Podcast-Tutorial.png
:alt: Add item in data displayed
......@@ -265,23 +274,24 @@ To go further, we need to create our own widget template using the ``solid-widge
.. code-block:: html
<solid-widget name="podcast-episode">
<template>
<solid-display
data-src="${value}"
fields="title, meta(pubDate, itunes:duration), description"
widget-title="h2"
widget-description="p"
/>
</template>
</solid-widget>
<solid-widget name="podcast-episode">
<template>
<solid-display
data-src="${value}"
fields="title, meta(pubDate, itunes:duration), description"
widget-title="h2"
widget-description="p"
/>
</template>
</solid-widget>
<solid-display
data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
[...]
multiple-item="podcast-episode"
no render
/>
<solid-display
data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
[...]
multiple-item="podcast-episode"
no render
/>
``solid-widget`` tag must be used with ``template`` to avoid its content to be rendered during the first page display.
The code included in the template is then used by Startin'blox to render each item. And you can use here again all the
......@@ -298,7 +308,7 @@ When a custom widget template is used, it gets a javascript variable called ``va
displayed directly in the template using ``${value}`` or you can apply some Javascript to it before. For example, here is how
to format the date using the browser locale settings :
.. code-block:: html
.. code:: html
<solid-widget name="format-date">
<template>
......@@ -313,26 +323,28 @@ Now if I use ``widget-pubDate="format-date"`` in ``<solid-widget name="podcast-e
And this template mechanism plays also nicely with other HTML5 standard tags, such as ``audio`` :
.. code-block:: html
<solid-widget name="audio-player">
<template>
<audio src="${value}" controls/>
</template>
</solid-widget>
.. code:: html
<solid-widget name="audio-player">
<template>
<audio src="${value}" controls/>
</template>
</solid-widget>
<solid-widget name="podcast-episode">
<template>
<solid-display
data-src="${value}"
fields="title, meta('Épisode du ', pubDate, ' - ', itunes:duration), description, enclosure.url"
widget-title="h2"
widget-description="p"
widget-pubDate="format-date"
widget-enclosure.url="audio-player"
/>
</template>
</solid-widget>
<solid-widget name="podcast-episode">
<template>
<solid-display
data-src="${value}"
fields="title, meta('Épisode du ', pubDate, ' - ', itunes:duration), description, enclosure.url"
widget-title="h2"
widget-description="p"
widget-pubDate="format-date"
widget-enclosure.url="audio-player"
/>
</template>
</solid-widget>
.. figure:: ../../_static/images/import_documentation/podcast_tutorial/Render10-Podcast-Tutorial.png
:alt: Add audio player solid-widget
......@@ -347,4 +359,4 @@ check this is working with other podcasts (provided that CORS headers are set on
You can find the code on `this repository <https://git.startinblox.com/fabien4vo/solid-podcast>`__.
To learn more about the Startin'blox components and features, they are detailed in the `Framework guide <framework-guide-intro>`__.
To learn more about the Startin'blox components and features, they are detailed in the :ref:`Framework guide <framework-guide-intro>`.
source/import_documentation/first_step/sib-presentation.rst
View file @ 405339e9
......@@ -39,7 +39,7 @@ A front framework
**Startin'blox mainly develops a solution for creating web applications based on front-end development.**
It can be imported by a simple script in a html file and provides you basics functionalities like making a form, displaying data, a map, a calendar etc..
To learn more about the framework components and features, they are detailed in the `Framework guide <framework-guide-intro>`__.
To learn more about the framework components and features, they are detailed in the :ref:`Framework guide <framework-guide-intro>`.
In the Startin'blox philosophy, the logic of the data processing is done on the front side.
......@@ -58,7 +58,7 @@ Each component treats a specific shape of data. The validation of this shape is
A server solution
.................
We offer a server solution based on the `Django framework <https://www.djangoproject.com/>`__ and adapted to be compatible with
the Linked datas platform conventions, named DjangoLDP.
the Linked datas platform conventions, named :ref:`DjangoLDP <djangoldp-guide-intro>`.
It is a simple architecture on which we can add LDP packages, corresponding to the different components used.
Those are the ones that will do the work of validating the application data.
......@@ -79,19 +79,17 @@ The solution can be summarized as follows:
Overview of the Framework
~~~~~~~~~~~~~~~~~~~~~~~~~
.. warning::
The section should be improve
Here is a brief presentation:
.. figure:: ../../_static/images/import_documentation/Framework-Overview.png
:alt: Framework Overview
`To go deeper <https://git.happy-dev.fr/startinblox/framework/sib-core/>`__.
The framework is composed of **base components** that allow data to be displayed, modified, searched ... These functionalities are defined by attributes, specific to the components themselves or proposed by the framework **mixins**.
Finally, the **store** is responsible for managing the data.
To go deeper in the framework discovery and understanding, go to consult :ref:`framework guide introduction <framework-guide-intro>`, or take a look at `source code <https://git.startinblox.com/framework/sib-core>`__.
Follow the :ref:`Startin'blox podcast tutorial <podcast-tutorial>` offers a step-by-step introduction to the framework.
Why use Startin'blox ?
......
source/import_documentation/framework_guide/attributes-list.rst
View file @ 405339e9
......@@ -9,6 +9,10 @@ Attributes are specific to base components or they depend on mixins (they can be
~~~~~~~~~~~~~~~~~~
* :ref:`widget-mixin <action-field>`
``addable-[field]``
~~~~~~~~~~~~~~~~~~
* :ref:`widget API reference <reference>`
``alt-[field]``
~~~~~~~~~~~~~~~
* :ref:`widget-mixin <alt-field>`
......@@ -75,9 +79,14 @@ Attributes are specific to base components or they depend on mixins (they can be
~~~~~~~~~~~~~~~~~~~~
* :ref:`counter-mixin <counter-mixin>`
``data-holder``
~~~~~~~~~~~~~~~
* :ref:`solid-widget <solid-widget>`
``data-src``
~~~~~~~~~~~~
* :ref:`store-mixin <data-src>`
* :ref:`solid-widget <solid-widget>`
``data-label``
~~~~~~~~~~~~~~
......@@ -168,6 +177,10 @@ Attributes are specific to base components or they depend on mixins (they can be
~~~~~~~~
* :ref:`solid-lang <solid-lang>`
``limit``
~~~~~~~~~~~~~~~
* :ref:`server-pagination-mixin <server-pagination-mixin>`
``loader-id``
~~~~~~~~~~~~~
* :ref:`store-mixin <loader-id>`
......@@ -216,6 +229,10 @@ Attributes are specific to base components or they depend on mixins (they can be
~~~~~~~~~~~~~
* :ref:`store-mixin <no-render>`
``offset``
~~~~~~~~~~~~~~~
* :ref:`server-pagination-mixin <server-pagination-mixin>`
``order-asc``
~~~~~~~~~~~~~
* :ref:`sorter-mixin <sorter-mixin>`
......
source/import_documentation/framework_guide/how-to-use-SIB.rst 0 → 100644
View file @ 405339e9
.. _framework-guide-frequent-questions:
Examples of Startin'blox use cases
==================================
This page contains frequently asked questions about the use of the framework,
with a link to the appropriate page or the presentation of an example with the html code and the rendering.
How to display data
-------------------
The :ref:`podcast tutorial <podcast-tutorial>` illustrates with details how to display data.
To present it really simply, a ``solid-display`` component with a ``data-src`` attribute whose value is jsonld file with dataset to work on (the ``fields`` attribute precise the fields to display):
.. code-block:: html
<solid-display
data-src="data/documentation/users.jsonld"
fields="first_name, last_name"
></solid-display>
<solid-display
data-src="data/documentation/user-1.jsonld"
fields="first_name, last_name"
></solid-display>
The first solid-display displays data for a **container** (several resources), the second from a **resource**.
.. figure:: ../../_static/images/import_documentation/framework-basic-use/display-data.png
:alt: 2 examples of solid-display use
Here is the jsonld data structure used for the example (container and resource):
.. figure:: ../../_static/images/import_documentation/framework-basic-use/jsonld-container.png
:alt: Example of jsonld data container
.. figure:: ../../_static/images/import_documentation/framework-basic-use/jsonld-resource.png
:alt: Example of jsonld data resource
How to display nested data
--------------------------
Nested data is a data linked to another but not stored in the same place.
They are related by a "call" from the first data to the stored place of the second one.
Startin'blox proposes 2 ways to display it:
* **period** syntax
* ``nested-field`` attribute
.. code-block:: html
<solid-display
data-src="data/documentation/user-1.jsonld"
fields="profile.address, profile.birthdate"
widget-profile.address="solid-display-div-multiline"
widget-profile.birthdate="solid-display-div-date"
></solid-display>
<solid-display
data-src="data/documentation/user-1.jsonld"
nested-field="profile"
fields="address, birthdate"
widget-address="solid-display-div-multiline"
widget-birthdate="solid-display-div-date"
></solid-display>
The widgets are used to specify how data is displayed. Their use is detailed in :ref:`widgets API <reference>` and :ref:`examples <widgets-examples>` of use are presented.
.. figure:: ../../_static/images/import_documentation/framework-basic-use/nested-data.png
:alt: nested-data
How to add and edit data
------------------------
To create a form, indicate in ``data-src`` attribute the data model to which it corresponds. If the data model is a **resource**, the form will be used to edit data. If it's a **container**, the form will create a new resource.
The solid-form component is automatically linked to the data, it takes care of adding or editing them.
Then, add attributes and widgets to change label values, precise inputs type, etc.
.. code-block:: html
<solid-form
data-src="data/documentation/user-1.jsonld"
fields="first_name, last_name, email"
label-first_name="First name:"
label-last_name="Last name:"
label-email="Email:"
></solid-form>
<solid-form
data-src="data/documentation/concerts.jsonld"
fields="date, artist, start_time, end_time, scene, gauge"
label-date="Date:"
label-artist="Artist:"
label-start_time="Start time:"
label-end_time="End time:"
label-scene="Scene:"
label-gauge="Gauge:"
widget-date="solid-form-date-label"
widget-start_time="solid-form-time-label"
widget-end_time="solid-form-time-label"
widget-gauge="solid-form-number-label"
></solid-form>
.. figure:: ../../_static/images/import_documentation/framework-basic-use/solid-form.png
:alt: Example of solid-form use
How to add new values in a form
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The feature ``addable`` adds a solid-form to add a value to a field. Here, hobbies is concerned:
.. code-block:: html
<solid-form
data-src="data/documentation/users.jsonld"
fields="first_name, last_name, hobbies"
label-first_name="First name:"
label-last_name="Last name:"
label-hobbies="Hobbies:"
submit-button="Send form"
widget-hobbies="solid-form-dropdown-addable-label"
range-hobbies="data/documentation/hobbies.jsonld"
addable-hobbies-fields="name"
addable-hobbies-widget-name="solid-form-text-label"
addable-hobbies-label-name="Add a new hobby:"
addable-hobbies-submit-button="Add hobby"
></solid-form>
The red frame represents the widget tag ``solid-form-dropdown-addable-label``,
the blue frame represents the ``<solid-form>`` created by ``addable`` attribute:
.. figure:: ../../_static/images/import_documentation/framework-basic-use/solid-form-addable.png
:alt: Example of solid-form with addable feature
Specific case - how to add and edit nested data
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To modify or add data including data linked, adding a second solid-form is necessary, with ``data-holder`` and ``data-src=${value}`` attributes. It can be done thanks to a custom solid-widget. The second-form can also contain attributes:
.. code-block:: html
<solid-form
data-src="data/documentation/users.jsonld"
fields="first_name, last_name, email, profile"
label-first_name="First name:"
label-last_name="Last name:"
label-email="Email:"
widget-profile="profile-form"
></solid-form>
<solid-widget name="profile-form">
<template>
<b>Profile form</b>
<solid-form
data-holder
data-src="${value}"
naked
fields="birthdate, address, phone"
label-birthdate="Birthdate:"
label-address="Address:"
label-phone="Phone number:"
></solid-form>
</template>
</solid-widget>
.. figure:: ../../_static/images/import_documentation/framework-basic-use/solid-form-nested.png
:alt: Example of solid-form nested
For more informations, ``data-holder``, ``data-src="${value}"`` attributes are detailed in :ref:`solid-widget<solid-widget>`
and ``naked`` attribute in :ref:`solid-form<solid-form>`.
How to display data in a table
------------------------------
To display data in a table, instead of a ``solid-display``, use a ``solid-table``, specific attributes are detailed on its :ref:`presentation page <solid-table>`.
The ``order-asc`` attribute allows to sort data elements by date. It is presented on :ref:`sorter-mixin page <sorter-mixin>`.
.. code-block:: html
<solid-table
data-src="data/documentation/concerts.jsonld"
fields="artist, date, start_time, end_time, scene"
></solid-table>
<solid-table
data-src="data/documentation/concerts.jsonld"
fields="artist, date, start_time, end_time, scene"
widget-date="solid-display-div-date"
widget-start_time="solid-display-div-time"
widget-end="solid-display-div-time"
header
label-artist="Artist"
label-date="Date"
label-start_time="Start time"
label-end_time="End time"
label-scene="Scene"
order-asc="date"
></solid-table>
.. figure:: ../../_static/images/import_documentation/framework-basic-use/solid-table.png
:alt: 2 examples of solid-table use
Jsonld data structure used for the example:
.. figure:: ../../_static/images/import_documentation/framework-basic-use/jsonld-solid-table.png
:alt: Example of jsonld data container
How to filter displayed data
----------------------------
From the example above, by adding ``filtered-by`` attribute reffering to a ``solid-form-search`` component, data displayed can be filtered:
.. code-block:: html
<solid-form-search
id="test"
fields="artist"
label-artist="Search by artist :"
></solid-form-search>
<solid-table
data-src="data/documentation/concerts.jsonld"
fields="artist, date, start_time, end_time, scene"
widget-date="solid-display-div-date"
widget-start_time="solid-display-div-time"
widget-end="solid-display-div-time"
header
label-artist="Artist"
label-date="Date"
label-start_time="Start time"
label-end_time="End time"
label-scene="Scene"
order-asc="date"
filtered-by="test"
></solid-table>
.. figure:: ../../_static/images/import_documentation/framework-basic-use/solid-form-search.png
:alt: Solid-form-search example
.. figure:: ../../_static/images/import_documentation/framework-basic-use/data-filtered.png
:alt: Data filtered example
How to display a list of nested data - ``multiple`` attribute use
-----------------------------------------------------------------
To display a list of data, they have to be in a container.
If the data to be listed are nested, add ``multiple-[field]`` attribute from :ref:`widget-mixin <widget-mixin>` to precise which field to display.
.. code-block:: html
<solid-display
data-src="data/documentation/user-5.jsonld"
fields="first_name, last_name, email, hobbies"
></solid-display>
<solid-display
data-src="data/documentation/user-5.jsonld"
fields="first_name, last_name, email, hobbies"
multiple-hobbies
multiple-hobbies-fields="name"
></solid-display>
.. figure:: ../../_static/images/import_documentation/framework-basic-use/nested-data-list.png
:alt: List of nested data in a container
.. figure:: ../../_static/images/import_documentation/framework-basic-use/jsonld-nested-data-list.png
:alt: Jsonld file used for nested data list
File hobby-1.jsonld content:
.. code-block:: json
{
"@id": "/examples/data/documentation/hobby-1.jsonld",
"name": "Comics",
"@context": "https://cdn.happy-dev.fr/owl/hdcontext.jsonld"
}
How to use default and empty attributes
---------------------------------------
* **default-widget** defines the widget used by default for all the fields if none is specified:
Here, default-widget is applied to ``email`` and ``last_name`` (``first_name`` has its own one).
.. code-block:: html
<solid-display
data-src="data/documentation/user-1.jsonld"
fields="first_name, last_name, email"
></solid-display>
<solid-display
data-src="data/documentation/user-1.jsonld"
fields="first_name, last_name, email"
widget-first_name="b"
default-widget="solid-display-link"
></solid-display>
.. figure:: ../../_static/images/import_documentation/framework-basic-use/default-widget.png
:alt: default-widget example
* **default-[field]** defines the ``value`` by default, **default-widget-[field]** defines a widget by default for an empty or undefined ``[field]``:
.. code-block:: html
<solid-display
data-src="data/documentation/profile-2.jsonld"
fields="birthdate, phone"
default-phone="No phone number"
></solid-display>
<solid-display
data-src="data/documentation/profile-2.jsonld"
fields="birthdate, phone"
default-widget-phone="default-widget-phone"
></solid-display>
.. figure:: ../../_static/images/import_documentation/framework-basic-use/default-(widget)-field.png
:alt: default-[field] and default-widget-[field] example
.. figure:: ../../_static/images/import_documentation/framework-basic-use/default-field-data.png
:alt: data for default-[field] example
* **empty-widget** and **empty-value** allow to display a widget with a value if there is no data in a container :
.. code-block:: html
<solid-display
data-src="data/documentation/user-3-hobbies.jsonld"
fields="name"
empty-value="No hobby"
empty-widget="no-hobby"
></solid-display>
<solid-widget name="no-hobby">
<template>
<b>Empty container</b>
${value}
</template>
</solid-widget>
.. figure:: ../../_static/images/import_documentation/framework-basic-use/empty-widget.png
:alt: empty-widget and empty-value example
.. figure:: ../../_static/images/import_documentation/framework-basic-use/empty-widget-data.png
:alt: data for empty-widget example
* **empty-[set]** and **empty-[set]-value** allow to display a widget with a value if all fields in a :ref:`set<widget-mixin>` are empty:
.. code-block:: html
<solid-display
data-src="data/documentation/profile-4.jsonld"
fields="fullname, contact(address, phone)"
empty-contact="empty-set"
empty-contact-value="No contact information"
></solid-display>
<solid-widget name="empty-set">
<template>
<b>Contact :</b>
<p>${value}</p>
</template>
</solid-widget>
.. figure:: ../../_static/images/import_documentation/framework-basic-use/empty-set.png
:alt: empty-[set] and empty-[set]-value example
.. figure:: ../../_static/images/import_documentation/framework-basic-use/empty-set-data.png
:alt: data for empty-[set] example
How to use special attributes, values
-------------------------------------
store://...
~~~~~~~~~~~
It allows to fetch from the :ref:`store <store-mixin>` and display any value from any data resource, for any concerned attribute.
*Here, without it, the field's name is displayed by default.*
.. code-block:: html
<solid-display
data-src="data/documentation/users.jsonld"
fields="full_name"
action-full_name="user-details"
></solid-display>
<solid-display
data-src="data/documentation/users.jsonld"
fields="full_name"
action-full_name="user-details"
link-text-full_name="store://resource.full_name"
></solid-display>
.. figure:: ../../_static/images/import_documentation/framework-basic-use/store-use.png
:alt: Example of store://... value use
bind-resources
~~~~~~~~~~~~~~
It allows to keep and pass the resource data-src between views when a :ref:`solid-router <solid-router>` is used.
*Here, it ensures the personal informations of user clicked are displayed.*
.. code-block:: html
<solid-router use-hash>
<solid-route
hidden
use-id
name="user-details"
></solid-route>
</solid-router>
<solid-display
data-src="data/documentation/users.jsonld"
fields="full_name"
action-full_name="user-details"
link-text-full_name="store://resource.full_name"
></solid-display>
<div data-view="user-details" hidden>
<solid-display
bind-resources
fields="first_name, last_name, email, profile.birthdate, profile.address, profile.phone"
label-first_name="First name :"
label-last_name="Last name :"
label-email="Email :"
label-profile.birthdate="Birthdate :"
label-profile.address="Address :"
label-profile.phone="Phone number :"
default-widget="solid-display-value-label"
></solid-display>
</div>
.. figure:: ../../_static/images/import_documentation/framework-basic-use/bind-resources.png
:alt: Example of bind-resources use
source/import_documentation/framework_guide/javascript-API.rst
View file @ 405339e9
......@@ -6,6 +6,6 @@ This section presents how you can use Javascript API with sib-core.
.. toctree::
:maxdepth: 1
Events <events>
Javascript Helpers <javascript-helpers>
Store documentation <store-documentation>
\ No newline at end of file
/import_documentation/javascript_API/Events
/import_documentation/javascript_API/Helpers-functions
/import_documentation/javascript_API/Store-doc
\ No newline at end of file
source/import_documentation/framework_guide/list-base-components.rst
View file @ 405339e9
......@@ -4,18 +4,29 @@ Base components
These components offer basic functionalities used in
an simple web application like display data, create data, search data, etc.
The base components are :
- ``Solid-Ac-Checker`` : to manage permissions
- ``Solid-Calendar`` : to display and manage data on a calendar
- ``Solid-Delete`` : to delete data
- ``Solid-Display`` : to display data
- ``Solid-Form`` : to create forms and modify data
- ``Solid-Form-Search`` : to search data
- ``Solid-Lang`` : to manage language
- ``Solid-Map`` : to display and manage data on a map
- ``Solid-Table`` : to manage data on a table
- ``Solid-Widget`` : to create custom elements (pattern) to display data
To find out how to use them :
.. toctree::
:maxdepth: 1
solid-ac-checker <solid-ac-checker>
solid-calendar <solid-calendar>
solid-display <solid-display>
solid-delete <solid-delete>
solid-form <solid-form>
solid-form-search <solid-form-search>
solid-lang <solid-lang>
solid-map <solid-map>
solid-table <solid-table>
solid-widget <solid-widget>
\ No newline at end of file
/import_documentation/Components/Solid-Ac-Checker
/import_documentation/Components/Solid-Calendar
/import_documentation/Components/Solid-Delete
/import_documentation/Components/Solid-Display
/import_documentation/Components/Solid-Form
/import_documentation/Components/Solid-Form-Search
/import_documentation/Components/Solid-Lang
/import_documentation/Components/Solid-Map
/import_documentation/Components/Solid-Table
/import_documentation/Components/Solid-Widget
source/import_documentation/framework_guide/list-external-components.rst
View file @ 405339e9
......@@ -2,10 +2,15 @@ External components
*******************
The external components are not required for an application to be functional,
however they can be used to add useful features such as authentication and router:
however they can be used to add useful features :
- ``Solid-Auth`` : to manage user authentication
- ``Solid-Router`` : to create menu and navigate between pages
For more information on their use :
.. toctree::
:maxdepth: 1
solid-auth <sib-auth>
solid-router <solid-router>
/import_documentation/Components/Solid-Auth
/import_documentation/Components/Solid-Router
source/import_documentation/framework_guide/list-external-components2.rst 0 → 100644
View file @ 405339e9
External components
*******************
The external components are not required for an application to be functional,
however they can be used to add useful features :
- ``Solid-Auth`` : to manage user authentication
- ``Solid-Router`` : to create menu and navigate between pages
For more information on their use :
test 1
.. toctree::
:maxdepth: 1
/import_documentation/Components/Solid-Auth
/import_documentation/Components/Solid-Router
test 2
.. toctree::
:maxdepth: 1
Solid-Auth to manage user authentication </import_documentation/Components/Solid-Auth>
Solid-Router : to create menu and navigate between pages </import_documentation/Components/Solid-Router>
test 3
.. toctree::
:maxdepth: 1
**Solid-Auth** : to manage user authentication <sib-auth>
``Solid-Router`` : to create menu and navigate between pages <solid-router>